Native apps: the app manifest, links, development on a phone and store releases
An app built with duolith build --target native runs in the shells in native/ (Android and iOS). This page covers everything that makes it your app rather than the shell: its name, id, icon and launch screen, the links that open it, running it on a phone while you edit, and building a signed release for Google Play and the App Store. The runnable app is examples/field-notes:
duolith build examples/field-notes --target native
duolith dev examples/field-notes --target android --host
Decisions: 0140 (the app manifest and duolith ship), 0141 (links, opening other sites, the dev server and the preview app).
The app manifest
The app group of duolith.yaml says what the native build writes into the Android and iOS projects:
app:
name: Field Notes # the app's name (required)
display-name: Notes # under the icon; the name when left out
id: dev.duolith.fieldnotes # bundle id and application id (required); cannot change once published
version: 1.0.0 # MAJOR.MINOR.PATCH, shown in the stores (required)
build: 1 # a whole number, raised for every store upload (duolith ship needs it)
icon: assets/icon.png # a square PNG of 1024 pixels or more (duolith ship needs it)
splash:
image: assets/splash.png # shown centred while the app starts, 512 to 4096 pixels; the icon when left out
background: { light: "#f6f5f2", dark: "#111214" } # or one "#rrggbb"; the theme's canvas when left out
orientation: portrait # portrait, landscape or any (the default)
ios:
minimum: "15.0" # the oldest iOS, 13.0 to 26.x, in quotes (15.10 unquoted is 15.1)
team: ABCDE12345 # the Apple team that signs it: ten capital letters and digits
id: dev.duolith.field-notes # when iOS's id must differ: letters, digits, - and .
android:
minimum: 26 # the oldest API level, 24 to 35
id: dev.duolith.field_notes # when Android's id must differ: letters, digits and _
links:
domains: [notes.example.com] # https links on these hosts open the app
scheme: fieldnotes # fieldnotes://... opens the app
duolith build --target native checks it, with the line of each problem (E0470 to E0477; duolith explain E0472 says more), and writes, under dist-native/native/. A duolith.yaml that is not YAML at all (a tab used to indent, a bracket left open) fails duolith build, duolith dev and duolith ship at the line the YAML reader stopped on (E0484); it is never read as a file without an app group.
The id is the hardest setting to get right, since it cannot change once the app is in a store. iOS takes letters, digits, - and . in a bundle id; Android takes letters, digits and _, with every part starting with a letter. So id: must be one both take, such as com.example.fieldnotes: com.example.field_notes is refused for iOS and com.example.field-notes for Android (E0472 names the platform). When the two must differ, give ios.id and android.id.
The files it writes:
| File | For |
|---|---|
assets/duolith-app.json | Both shells at run time: the environment values and the link domains and scheme |
android/AndroidManifest.app.xml | Merged over the shell's manifest: the name, icon, launch theme, orientation, link filters and the effects' permissions |
android/res/ | The name and launch background, the launcher icon at the five densities, the launch image |
android/assetlinks.json | To serve on each link domain (below) |
ios/Info.app.plist, ios/app.xcconfig | Merged into the Xcode project: names, version and build, orientations, URL scheme, launch screen; bundle id, oldest iOS, team |
ios/App.entitlements, ios/Assets.xcassets | Universal links; the 1024-pixel icon (transparency filled with white, as the App Store asks), the launch image and background |
ios/apple-app-site-association | To serve on each link domain (below) |
The Android shell's Gradle build reads them from the build it is given (-Pduolith.build=<dist-native>), and native/ios/App/prepare.sh <dist-native> copies them into the Xcode project. Without an app group the app runs with the shell's own name and id, which is fine for development, and duolith ship refuses it.
The build also writes the app's translations (locales/) and its privacy manifest (privacy/PrivacyInfo.xcprivacy) beside the bundle, as it does for the web. Both shells carry the translations as locales/<locale>.json: the Android build in the APK's assets, prepare.sh in the iOS app bundle.
Environment values
environment() reads the same values on a phone as on the web (decision 0021). For a native build, they come from the environment of the duolith build that made it: each DUOLITH_PUBLIC_ variable, by its camel-case name, so DUOLITH_PUBLIC_API_URL=https://api.example.com is apiUrl. Only DUOLITH_PUBLIC_ variables reach the app, since everything in it can be read by anyone who has it.
Scripts on a phone
A phone does not run the app's scripts in a browser's engine. On Android both of Lynx's threads run in PrimJS, Lynx's QuickJS engine, which goes up to ECMAScript 2019 and lacks the later built-ins such as Array.prototype.at, Object.hasOwn and String.prototype.replaceAll; on iOS the main thread is PrimJS too, and the background thread is the system's JavaScriptCore (iOS 13 or later). The native bundle lowers the syntax of every script, the app's own included, to those engines, and adds each missing built-in the code calls from core-js, plus queueMicrotask, which PrimJS lacks too, so use the language as on the web.
Links that open the app
With links.domains, an https link on one of those hosts opens the app instead of the browser (Android App Links, iOS universal links); with links.scheme, so does fieldnotes://.... The app opens on the screen at the link's path: https://notes.example.com/notes/2?from=mail and fieldnotes://notes/2?from=mail both open /notes/[id] with id 2 and the query from=mail, whether the app was closed or running.
Each system checks that you own the domain, from a file the domain serves:
- Android: serve
assetlinks.jsonathttps://notes.example.com/.well-known/assetlinks.json, withsha256_cert_fingerprintsset to your release key's fingerprint (keytool -list -v -keystore upload.keystore, or Play Console's App signing page when Google signs the app). Until it is served, Android asks which app should open the link. - iOS: serve
apple-app-site-associationathttps://notes.example.com/.well-known/apple-app-site-association, asapplication/json, with no redirect. It names<team>.<bundle id>, so giveios.team.
Code that needs the whole address, such as sign-in finishing a magic link, hears it from @duolith/client/native:
import { lastLink, onLink } from "@duolith/client/native";
const stop = onLink((url) => finishSignIn(url)); // each link that opens the app from now on
const opening = lastLink(); // the last one, including the one that started the app
For a magic link, send people to an https address on one of the link domains (or the app's scheme), so the link opens the app on the phone they read their mail on.
Opening other sites
An href to another site (https://, http://, mailto:, tel: or sms:) opens in the system's browser or app on a phone, as it opens in a new tab on the web. The shells' openUrl does it (Android's ACTION_VIEW, iOS's UIApplication.open). No other scheme is opened: an href written as text with another, such as javascript: or file:, fails the build (E0170), and one built from data is refused by the engine and again by each shell, so it never reaches the system.
Running on a phone while you edit
duolith dev examples/field-notes --target android # or --target ios
It builds the app, bundles it, serves the bundle at http://localhost:4321 (or --port), and builds again on every change; each running app loads the new bundle at once. It prints how to point a phone at it:
- Android emulator or a phone on USB:
adb reverse tcp:4321 tcp:4321, then the shell's debug build with-Pduolith.devServer=http://localhost:4321(or start it withadb shell am start -n <id>/dev.duolith.shell.MainActivity -e duolithDevServer http://localhost:4321). - iOS simulator:
xcrun simctl launch booted <bundle id> -duolithDevServer http://localhost:4321. - A phone on the same Wi-Fi: add
--host, so it listens on the network, and scan the QR code it prints with the preview app.
Only debug builds load from a dev server; a release build always runs its own bundle. The reload socket takes only a shell, which sends no Origin, and the dev server's own page, so a web page elsewhere in the computer's browser cannot listen to it. A link that opens the app before it has fetched its file from the dev server waits for it, and the app opens on it.
The preview app
native/preview-app is the shell with a scan screen in front and no app of its own: install it once, scan the code duolith dev --host prints, and the app opens, reloading on each change. A phone's own camera works too: the code opens the dev server's page, whose "Open in the preview app" link opens it. Any web page can send a duolith-preview:// link, so the preview app asks before it opens the app a link names. Build it with native/android/gradlew -p native/preview-app/android assembleDebug, or on a Mac with the steps in native/preview-app/README.md. Its debug build loads from the computer over plain http; a release build of it allows no plain http (Android) or only local addresses (iOS). It cannot have your app's name, icon, link domains or unusual permissions; for those, run the shell's own debug build as above.
Store releases
duolith ship android [project] [--upload] [--track internal|alpha|beta|production] [--rollout <percent>]
duolith ship ios [project] [--upload]
duolith ship checks everything a store needs before it builds anything, and lists every problem at once: the app manifest with build and icon (E0470 to E0477, E0471), a build number above the last one it shipped (E0485), the signing configuration (E0478), a Mac for iOS (E0479) and, with --upload, the store's credentials (E0480). Then it builds for native, bundles, and hands over to the platform's tools (E0483 if one fails). The result is in <project>/dist-ship/android/<id>-<version>-<build>.aab or dist-ship/ios/...ipa. Raise build before each upload; both stores refuse a build number they already have, so duolith ship refuses one that is not above the highest in dist-ship/, and duolith build and duolith dev warn about it. Projects made with duolith create ignore dist-native/, dist-ship/ and .duolith/ in git.
Android: Google Play
- Make an upload key, once, and keep it out of the repository: ``
sh keytool -genkeypair -v -keystore upload.keystore -alias upload -keyalg RSA -keysize 2048 -validity 10000
- Give it to duolith ship through the environment, so no secret is ever on a command line or in a file: ``
sh export DUOLITH_ANDROID_KEYSTORE=$HOME/keys/upload.keystore export DUOLITH_ANDROID_KEYSTORE_PASSWORD=... DUOLITH_ANDROID_KEY_ALIAS=upload DUOLITH_ANDROID_KEY_PASSWORD=... duolith ship android examples/field-notes`It runs the shell's./gradlew bundleRelease`, which also refuses (E0478) a release without signing.
- The first upload is by hand: create the app in Play Console, turn on Play App Signing, and upload the
.aabto the internal testing track. Play then knows the app id. - Later uploads can be automatic. In Google Cloud, make a service account and a JSON key for it; in Play Console, Users and permissions, invite its email with release rights for the app. Then: ``
sh export DUOLITH_PLAY_SERVICE_ACCOUNT=$HOME/keys/play-account.json duolith ship android examples/field-notes --upload --track production --rollout 10`It makes an edit, uploads the bundle, sets the track's release (to every user, or with--rolloutto that share of them as a staged rollout, which you widen in Play Console) and commits the edit. If any step fails, it deletes the edit, so none is left open in Play Console.--trackdefaults tointernal, which releases to every tester at once, so--rollout` there is refused before anything is built.
iOS: the App Store
duolith ship ios runs on a Mac with Xcode, XcodeGen and CocoaPods (brew install xcodegen cocoapods); elsewhere it stops with E0479. It needs the Apple team that signs the app, as app.ios.team or DUOLITH_IOS_TEAM_ID (the team id is on the Membership page of developer.apple.com), and Xcode signed in to an account of that team (Xcode, Settings, Accounts), since it signs automatically.
- Create the app in App Store Connect with the same bundle id.
- Ship:
duolith ship ios examples/field-notes. It copies the build into the Xcode project (prepare.sh), writes the project (xcodegen generate), installs Lynx (pod install), archives a Release build and exports it for App Store Connect. - Upload, by hand with Apple's Transporter app, or with
--uploadand an App Store Connect API key (Users and Access, Integrations, with the App Manager role): ``sh export DUOLITH_ASC_KEY_ID=ABC123DEFG DUOLITH_ASC_ISSUER_ID=... DUOLITH_ASC_KEY_PATH=$HOME/keys/AuthKey_ABC123DEFG.p8 duolith ship ios examples/field-notes --upload`The key is copied into a private temporary folder outside the project forxcrun altool`, and the folder is removed however the upload ends, so it is never left beside the build. The build then appears in TestFlight after Apple processes it; you submit it for review in App Store Connect.
In CI
Both commands read everything secret from the environment, so a CI job sets the variables from its secrets store (writing the keystore, service account key and .p8 to files first) and runs duolith ship android --upload, or duolith ship ios --upload on a macOS runner.
What still needs a phone
The shells' behaviour on a device (links verified by each system, the launch screen, reloads from a dev server, signing and uploads with real accounts) is listed in native/DEVICE-CHECKLIST.md. The iOS code has not been compiled in this repository's environment; CI compiles the shell's Swift package on macOS, and builds the app project with field-notes for the simulator, unsigned and without the Lynx pod, checking that the built app has the manifest's bundle id, oldest iOS, version and build number.