0051. Permission declarations are written at build time from the effects an app imports
- 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
iOS refuses to show a permission prompt, and App Review rejects the app, without a usage description in Info.plist for each permission the app asks for; Android needs <uses-permission> entries in the manifest, and Play flags apps that declare permissions they do not use. Writing these by hand drifts from what the app actually uses. The compiler already reads every page's script.
Decision
spec/effects/effects.yaml lists every export of @duolith/effects and the declarations each needs (camera: NSCameraUsageDescription, CAMERA and the optional camera feature; push: the remote-notification background mode and POST_NOTIFICATIONS; haptics: VIBRATE; purchases: BILLING), with a default usage description.
The analyzer reads the named imports of @duolith/effects in each page and component (effects_used). A name that is not in the catalogue, or a namespace import, is E0220; type-only imports count for nothing. The build takes the union over the app's own files and writes, under native/ in the build output:
ios/Info.permissions.plist: the usage descriptions and background modes, for the iOS shell to merge into its Info.plist;android/AndroidManifest.permissions.xml: a manifest fragment for Android's manifest merger;effects.json: the effects and declarations used, for the shells to link only those implementations.
An app replaces a usage description in an optional permissions.yaml at its root (camera: Scan receipts to add them to an expense.); a name there that has no usage description is E0221.
A permission is declared when the effect that needs it is imported anywhere in the app, not when permissions.request("camera") is called: the declaration is app-wide, and an app that asks for the camera also imports camera somewhere.
Alternatives considered
| Option | Why not |
|---|---|
| Declarations written by hand in the native projects | They drift; the app may declare what it no longer uses, or miss what it does |
Reading permissions.request("...") arguments | Only works for literal arguments, and adds a second way to declare |
| Usage descriptions as an option in page code | The build would have to evaluate script; a YAML file is data, like theme.yaml |
Declarations in a manifest the developer writes (Expo's app.json plugins) | A setting to keep in step with the code; conventions over configuration |
Consequences
A web build of an app that imports effects also writes native/ files beside the site; they are small and harmless to serve. The native shells (WP10) must merge them. Adding an effect that needs a permission means adding it to effects.yaml, which the analyzer and the build read with no code change.