Device effects
What a phone can do, imported by name from @duolith/effects and reactive like state. Each works on the web, Android and iOS. The full table, with each platform's API, is in packages/effects/README.md; the runnable tour is examples/device-effects.
import { connection, location, scanner } from "@duolith/effects";
Ask before you press
Every device effect says whether this platform can, before anything is called, so a page can hide a button or explain why it is missing:
<show when={scanner.available}>
<Button label="Scan" onPress={scan} />
</show>
<otherwise>
<text class="text-caption text-muted">{scanner.unavailableReason}</text>
</otherwise>
When a call is made anyway, it never does nothing. Where "it could not" is an answer, it is a result: review.request() and badge.set() resolve "unavailable", tracking.request() resolves "not-needed" off iOS, and calendar.addEvent() resolves "handed-off" on the web and Android, where the calendar's own editor takes the event, and "cancelled" when the user closes iOS's editor. Where the call has no outcome to give, it fails with an EffectError whose code names the reason (duolith explain E0425): picking a contact in Firefox fails with E0222, scanning without BarcodeDetector with E0425.
Permissions are asked for you, and only where needed
location.current(), recorder.start() and speech.listen() ask for their permission through permissions the first time, and fail with E0223 when the user says no. Where the system's own screen shares only what the user picks, nothing is asked: contacts (picked for a phone number or an email address, contacts.pick({ wants: "email" })), the calendar's editor (Android, and iOS 17 and later), the photo picker, and the scanner on Android (decision 0102). duolith build --target native writes the usage strings and manifest entries for the effects the app imports; the defaults are in spec/effects/effects.yaml.
A page that asks for a permission itself must have it declared:
await permissions.request("contacts");
// error[E0431]: permissions.request asks for contacts, which the app does not declare
Import the effect that uses it, or give it a reason in permissions.yaml, which both declares it and is the sentence the system shows:
contacts: To find your friends who use the app.
On a phone, a request whose usage description is missing anyway answers "unavailable" rather than stopping the app.
Files that last while the app runs
A recording's url and a picked file's url are copies in the app's cache on native. They last while the app runs; the next launch clears the earlier run's. Upload or keep what matters during the run.
The clipboard needs a press
Read the clipboard from a Paste button. Browsers and iOS ask the user, and Android, which would let the app read it at any time, reads it only within five seconds of the user's press or key: otherwise readText fails with E0422.
Watching
location.watch() and sensors.watch(name) return a function that stops the watch. Give it to onDispose so it stops with the screen:
onDispose(sensors.watch("heading", { interval: 200 }));
location.position, sensors.reading("heading"), connection.online, keyboard.height and every device value are state: a view that reads them updates by itself.
Addresses the browser opens
browser.open(url, { inApp }) opens only absolute http and https addresses. One the page's text gives that is neither fails the build with E0420, because an in-app browser cannot show it and a javascript: address must never run. That includes an address in a const, a template or a sum whose start is written, and open taken from the effect:
browser.open("https://example.com/terms", { inApp: true }); // fine
browser.open(`https://${host}/terms`); // fine: it starts as a web address
browser.open("/terms"); // error[E0420]: "/terms" is not an http or https address, so no browser can open it
browser.open(`ftp:${host}`); // error[E0420]: "ftp:…" is not an http or https address
const { open } = browser;
open("mailto:a@example.com"); // error[E0420]
Testing with mocks
Each effect takes another platform with use, and each has a mock:
import { location, mockLocation } from "@duolith/effects";
const phone = mockLocation({ position: { latitude: 48.8584, longitude: 2.2945 } });
location.use(phone);
phone.moveTo({ latitude: 48.86 }); // every watch hears it
permissions.use(mockPermissions({ location: "denied" })) stands in for the system's answers to permission prompts.
Mocks are for tests, and for trying an app in a desktop browser. A native build, which is what reaches the stores, refuses a page or component that imports one:
error[E0432]: mockLocation is a mock, and a native build does not ship one