Duolith docs

0140. The app manifest is a group of duolith.yaml, and duolith ship builds store releases from it

  • Status: Accepted (Mik, 16 Nov 2026), with the key names, the oldest systems, duolith ship and the Play upload through Node as written.
  • Date: 2026-11-14
  • Decided by: Mik (the file, the key names, the command); integrator (built on the recommendation meanwhile)
  • Planning item: none

Context

A native build ran with the shell's own identity: the name "Duolith", the id dev.duolith.shell, no icon, no launch screen. A real app needs its name, a bundle and application id, a version and build number, launcher icons at every density, a launch screen, an orientation, the oldest systems it runs on, and the links that open it, written into the Android manifest and Gradle build and into the iOS Info.plist, build settings and asset catalogue. People should write these once, not in two native projects, and a mistake (an id a store refuses, a 512-pixel icon) should be found before a build, since an id cannot change after publishing. Then the app needs a signed release a store takes.

Decision

  • Where: an app group in the project's duolith.yaml (beside lint), not a new file. Keys: name, display-name, id, version, build, icon, splash (image, background as #rrggbb or { light, dark }), orientation (portrait, landscape, any), ios (id, minimum, team), android (id, minimum), links (domains, scheme). Hyphenated like the rest of the file. spec/schemas/project.schema.json describes it, and a test keeps the schema and the reader's key lists equal.
  • Checked by duolith build --target native with E0470 to E0477, each at its line: unknown key or wrong kind, missing name, id or version, an id both stores do not accept (reverse-DNS, each part a letter then letters, digits or underscores), a version not MAJOR.MINOR.PATCH or a build outside 1 to 2100000000, an icon that is not a square PNG of 1024 pixels or more, a launch setting that cannot be used, an orientation or oldest system the shells do not take (iOS 13.0+, Android API 24 to 35), a link domain or scheme that cannot open the app (system schemes refused).
  • Written into dist-native/native/ by the build: an Android manifest merged over the shell's (with the effects' permissions), resources (name, launch background, icons at five densities drawn from the one image, the launch image), an iOS Info.plist merged by the app project's build phase, an xcconfig, entitlements and an asset catalogue (the icon flattened onto white), plus the assetlinks.json and apple-app-site-association files to serve. The image work is done in the Duolith command (the png crate), so no image tool is needed.
  • No app group is still a valid project: the shell's identity, for development. duolith ship requires the group with build and icon (E0471).
  • **duolith ship android|ios [project] [--upload]:** checks everything first and lists all problems at once (E0478 signing, E0479 not a Mac or no Xcode tools, E0480 no store credentials), then builds, bundles and runs the platform's tools (E0483 when one fails), into dist-ship/. Secrets come only from the environment (DUOLITH_ANDROID_KEYSTORE*, DUOLITH_PLAY_SERVICE_ACCOUNT, DUOLITH_IOS_TEAM_ID, DUOLITH_ASC_*), never from duolith.yaml or the command line. The Android shell's Gradle build refuses an unsigned release itself too. The Play upload (an edit, the bundle, the track with --rollout as a staged rollout, the commit) is a small Node script with no dependency, run as the bundler is; the App Store upload is xcrun altool with an API key.

Alternatives considered

OptionWhy not
A separate app.yaml or app.json (Expo's shape)One more file to find; duolith.yaml is already the project's settings and is schema-checked
Leave it to the native projects (edit the manifest and Info.plist by hand)Twice the work and easy to let drift; the shells are shared code, not the app's
fastlane for signing and uploadsA Ruby toolchain for two API calls on Android; on iOS it would wrap the same xcodebuild and altool steps
Signing secrets in duolith.yamlThey would be committed; the environment is what CI secret stores provide
Expo-style adaptive icons with separate foreground and backgroundMore to write for a first version; one square image covers both stores, and adaptive icons can be added as an optional key

Consequences

  • Every native build now writes these files; native-output.test.ts leaves them out of the bundle snapshots, and crates/cli/src/manifest/tests.rs checks them.
  • The Android shell reads the application id, version and oldest API from the build, and needs core-splashscreen; the iOS app project gains an xcconfig, an optional asset catalogue and a plist merge.
  • Mik to confirm: the key names (display-name, splash, links), the oldest systems (iOS 13, Android 7), building store releases from the Duolith command rather than documenting the native steps, and the Play upload through Node.