Mobile
Run, build, release, and instrument the Expo client that shares this backend.
apps/mobile is the mobile edition: one Expo client on the same Bun and Hono API the web app uses.
It is a client, not a second backend. The scope decision, including what stays out of it, is
docs/decisions/0005-mobile-edition-expo-client-on-the-existing-backend.md.
There is deliberately no on-device database. The API is the single source of truth, so the app
carries no schema, no migrations, and no sync policy — only TanStack Query over the typed Hono RPC
client. expo-sqlite/kv-store backs device preferences (theme, prompt state) and nothing else.
Prerequisites
Everything below the first row is a console step no command in this repository can do for you.
| Needed for | What to obtain |
|---|---|
| Anything at all | Node, pnpm, and either an iOS simulator (Xcode) or an Android emulator |
| Any build, update, or push | An Expo account, then npx eas init inside apps/mobile to claim a project ID |
| Shipping to the App Store | An Apple Developer Program membership and an App Store Connect app record |
| Shipping to Google Play | A Google Play Console developer account and an app record |
| Google sign-in on native | The existing Google OAuth web client — see below |
| Push on iOS | An APNs key, uploaded to EAS credentials |
| Push on Android | An FCM V1 service-account key, uploaded to EAS credentials |
npx eas init is required before the first build even for internal testing: a generated project
ships with no Expo project ID and no update URL on purpose, so it can never publish into someone
else's Expo project.
Stack
| Concern | Choice |
|---|---|
| Runtime | Expo SDK 58, React Native 0.88, React 19.3, new architecture |
| Navigation | expo-router with typed routes and Stack.Protected guards |
| Styling | react-native-unistyles 3, themed on the shared web design tokens |
| Motion | react-native-reanimated 4 with react-native-worklets |
| Data | TanStack Query over hc<AppType>(), no client-side cache of server rows |
| Forms | react-hook-form with the packages/contracts Zod schemas |
| Auth | Better Auth through @better-auth/expo and expo-secure-store |
| Lists | @legendapp/list |
| Keyboard | react-native-keyboard-controller |
| Crashes | @sentry/react-native, crash and error reports only, off without a DSN |
| Icons | lucide-react-native, rewritten to per-icon imports at build time |
Metro does not tree-shake, so a named import from the lucide-react-native barrel would bundle
every icon. plugins/babel-plugin-lucide-per-icon.js rewrites each named import to that icon's own
module, reading the mapping from the installed barrel, and fails the build on an import it cannot
map. Keep importing named icons from lucide-react-native; a namespace import is refused.
expo-dev-client is the supported way to run it. Expo Go cannot load the native modules this app
depends on, and the app does not target it.
Monorepo integration
apps/mobile is an ordinary pnpm workspace package. It needs no monorepo Metro configuration
and no nodeLinker change:
- Expo SDK 52 and newer configure Metro for monorepos automatically through
expo/metro-config, which is whymetro.config.jssets nowatchFoldersorresolver.nodeModulesPaths. It only starts from Sentry's Expo config, which stamps Debug IDs on release bundles and source maps, and dropsconsole.log,console.debug, andconsole.infofrom production bundles while keepingwarnanderror; - pnpm's default isolated
node_modulesworks.nodeLinker: hoistedis documented by Expo as a fallback for installations that break, not as a requirement, and switching it would change every install in this repository and weaken the phantom-dependency detectionpnpm kniprelies on.
If a native build ever fails to resolve a module through pnpm's symlinks, that fallback is the
escape hatch — set nodeLinker: hoisted in pnpm-workspace.yaml, re-install, and record why.
The app consumes two workspace packages: the shared contracts for wire schemas, and the server's
AppType for the typed client.
import type {AppType} from '@app/server'
import {NOTIFICATION_TYPE_INFO} from '@app/contracts'AppType must always be imported with import type. A value import would pull the entire server
tree — pg, bun:sql, node built-ins — into the Metro graph.
Configuration
| Variable | Purpose |
|---|---|
EXPO_PUBLIC_API_URL | Base URL of the API. Defaults to http://localhost:8000 when unset. |
APP_VARIANT | development selects the dev identity (see below). |
app.json is the canonical Expo configuration and app.config.js layers the development variant
over it: APP_VARIANT=development gives the app a .dev bundle identifier and package name and the
<app-name>-dev scheme, so a dev client and a store build coexist on one device.
The application scheme must match the server's MOBILE_APP_SCHEME. The server trusts <scheme>://
everywhere, <scheme>-dev:// outside production, and exp:// in development; see
Native clients.
runtimeVersion.policy is appVersion. An over-the-air update only reaches builds whose marketing
version matches, so app.json's version is what decides an update's audience. Keep it in step
with CHANGELOG.md through pnpm version:sync inside apps/mobile.
Local development
The repository owner starts development servers. With the API and database already running:
pnpm dev:mobileThat runs expo start --dev-client under the development variant. The first run needs a dev-client
build on the device or simulator:
cd apps/mobile
pnpm ios
pnpm androidPoint the client at a reachable API. localhost resolves to the simulator itself on a device, so
use the machine's LAN address when testing on hardware:
EXPO_PUBLIC_API_URL=http://192.168.1.10:8000 pnpm dev:mobileVerification commands:
cd apps/mobile
pnpm typecheck
pnpm test
pnpm doctor
pnpm prebuildtypecheck and test also run in the repository-wide vp run -r typecheck and vp run -r test,
and vp check formats and lints the app with everything else. A full expo export is deliberately
not part of vp run -r build, because bundling the app adds minutes to a pipeline that
otherwise finishes in seconds. It is pnpm build:mobile, and CI runs it as its own step whenever
apps/mobile exists, so a change that breaks Metro resolution or a Babel plugin fails before a
release build does.
The vitest suite covers framework-free modules only — deep-link parsing, error mapping, retry policy, upload rules, and the design-token generator. Screens need a React Native runtime the root pipeline does not host; they are covered by the device checks below.
Keyboard
Exactly one component owns keyboard movement on a screen. KeyboardProvider wraps the root layout,
and Screen scrollable renders a KeyboardAwareScrollView that scrolls the focused field above the
keyboard. Put every form inside Screen scrollable. Never add a KeyboardAvoidingView around or
inside it, and never subscribe to keyboard events in a screen: two owners compound their offsets and
hide the field on one platform.
KeyboardProvider runs with preload={false}. Preloading focuses a hidden UITextField at mount,
and that first focus cycle blocks the main thread while UIKit loads input modes; during a cold start
it hung launch for 2.4 seconds on a physical device. The first real focus pays that cost instead,
behind the keyboard's own animation.
Animation rules
Unistyles 3 and Reanimated 4 compose only one way. Keep the static Unistyles style in the style
prop and return only the values driven by shared values from the worklet:
style={[styles.card, animatedStyle]}. Never spread a Unistyles style into useAnimatedStyle.
- Read theme values inside a worklet through
useAnimatedThemefromreact-native-unistyles/reanimated, never throughUnistylesRuntime.getTheme()or a captureduseUnistyles()theme. - Call back into JavaScript with
scheduleOnRNfromreact-native-worklets, notrunOnJS. - Never call an animated ref (
ref()) inside a worklet. Since Reanimated 4.7 it is a shareable{value}on the UI runtime and throwsObject is not a function. Pass it tomeasureorscrollTo, which handle an unmounted view themselves. - Do not give the child of an animated view
flex: 1along its main axis; it can collapse to zero. Give it an explicit size.
Crash reporting
lib/sentry-options.ts configures Sentry for crashes and errors only. Tracing, profiling, replay,
logs, screenshots, view hierarchy, and failed-request capture are all off, and default PII is not
sent. Turning any of them on changes what leaves the device, so revise your privacy policy and store
privacy labels first. Sentry is disabled in development and in any build without
EXPO_PUBLIC_SENTRY_DSN, so nothing is required to run or ship the app.
Tap breadcrumbs are dropped. Since Sentry React Native 8.11 a tap breadcrumb carries the touched
view's accessibilityLabel, which on most screens is user content such as a name or a message.
Rage-tap breadcrumbs (ui.multiClick) are kept as a frustration signal and can carry the same
label; disclose that or drop them too.
The DSN is a public client key and ships in the binary. SENTRY_AUTH_TOKEN is the secret: it only
uploads source maps and native debug symbols during an EAS build. app.config.js turns that upload
on only when SENTRY_ORG, SENTRY_PROJECT, and SENTRY_AUTH_TOKEN are all set, so a build without
them still succeeds. Store all three as EAS environment variables:
npx eas env:create --environment production --name EXPO_PUBLIC_SENTRY_DSN --value <dsn> --visibility plaintext
npx eas env:create --environment production --name SENTRY_ORG --value <org> --visibility plaintext
npx eas env:create --environment production --name SENTRY_PROJECT --value <project> --visibility plaintext
npx eas env:create --environment production --name SENTRY_AUTH_TOKEN --value <token> --visibility secretReports carry EXPO_PUBLIC_APP_ENV, which the preview and production profiles set. Over-the-air
updates do not upload source maps, so a crash inside an update's JavaScript symbolicates only once
you upload that export's maps yourself.
Resolve an issue only once its fix reaches users, which for a mobile app is a store build or an update, not the commit.
Design tokens
constants/theme.ts is generated from packages/ui/styles/_variables.css, so the clients share one
palette instead of two drifting copies. The web tokens are oklch(), which React Native cannot
render, so the generator converts them to hex.
cd apps/mobile
pnpm theme:generateconstants/theme.test.ts regenerates from the current web tokens and fails when the checked-in
theme no longer matches, so a colour change on the web side cannot silently skip the app.
Authentication
The app uses Better Auth's Expo integration; there is no second session system. The complete flow, the trusted schemes, and the CSRF and CORS reasoning are in Native clients. In this app:
lib/auth-client.tsconfiguresexpoClientwithexpo-secure-store;lib/api-client.tsis the single place the stored session is replayed, as aCookieheader plus theexpo-originheader the server's origin check accepts;lib/deep-links.tsowns callback parsing and refuses a link from any other scheme.
Universal links
A magic-link sign-in hands the session back over the application's URI scheme. A custom scheme is claimed by whichever installed app registers it, and nothing stops a second app registering yours — so on a device where that happens, the sign-in link opens the wrong app. Universal links (iOS) and App Links (Android) close that: the operating system verifies the association against a file served from your own domain, and only your app can claim the URL.
Pass your web host when you scaffold and the configuration is written for you:
create-app my-app --mobile --app-domain app.example.comThat adds applinks: to ios.associatedDomains and a verified intentFilters entry covering
/auth and /invitations — the two paths whose emailed links should open the app. Without the
flag, neither key is written: a placeholder domain that silently fails verification is worse than an
absent one.
Two files then have to be served from that host, both over HTTPS, both without a redirect:
| Path | Contents |
|---|---|
/.well-known/apple-app-site-association | applinks with appIDs of <TeamID>.<bundleIdentifier>, served as application/json with no .json extension |
/.well-known/assetlinks.json | delegate_permission/common.handle_all_urls for your package name and its signing certificate SHA-256 |
npx eas credentials prints the Android signing SHA-256 to put in assetlinks.json; the iOS Team
ID is in your Apple Developer account. Until both files are live and verified, links fall back to
opening the browser — the custom scheme keeps working throughout, so this is a hardening step, not a
launch blocker.
Push notifications
Push closes the delivery-channel gate recorded in the 0.7.0 changelog entry. The mobile edition now owns registration, storage, delivery, and revocation.
Server side:
POST /push/devicesregisters or rotates a device token,GET /push/deviceslists them, andDELETE /push/devicesrevokes one;- a device row references the session that registered it, so signing out deletes it by cascade; deleting an account removes every device row in the same transaction as the session cleanup;
notifyUserdelivers through thepushchannel when the user's preference for that notification type allows it, and a token the provider reports asDeviceNotRegisteredis deleted.
Deployment:
PUSH_NOTIFICATIONS_ENABLED=true
EXPO_PUSH_ACCESS_TOKEN= # only when the Expo project enforces push securityWhile PUSH_NOTIFICATIONS_ENABLED is false the server still stores device tokens and honours
preferences; it logs the message instead of calling Expo. That is the zero-key local behaviour, not
a silent failure.
Client side, lib/push.ts requests permission, registers the Expo token, and revokes it on sign
out; hooks/useNotificationResponse.ts is the single place a tapped notification routes through,
and it handles cold starts as well as warm taps.
Push requires a physical device. A simulator returns unsupported from the registration flow.
Push credentials
Expo's push service is the delivery path, but the platform credentials are still yours:
cd apps/mobile
npx eas credentials # iOS: upload or let EAS generate an APNs key
npx eas credentials # Android: upload the FCM V1 service-account JSONWithout those, a token registers and the server records it, but the notification never leaves Expo.
Set PUSH_NOTIFICATIONS_ENABLED=true on the API only once they are in place; until then the server
logs each message instead, which is the intended local behaviour rather than a failure.
An Expo project with push security enabled also needs EXPO_PUSH_ACCESS_TOKEN on the API. Leave it
empty otherwise.
Google sign-in on native
The native flow keeps the OAuth exchange on the API origin through the Expo plugin's authorization proxy, so there is no second OAuth client and no new redirect URI:
- keep the existing web
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETon the API; - keep
SERVER_URL/auth/callback/googleas the only authorised redirect URI in the Google Cloud console; - register the app's scheme in
app.json, not in the Google console.
Native ID-token sign-in through @react-native-google-signin is a different path, is not enabled,
and would need separate iOS and Android OAuth client IDs plus an explicit audience decision.
EAS builds and submission
eas.json defines three profiles:
| Profile | Distribution | Channel | Notes |
|---|---|---|---|
development | internal | development | dev client, APP_VARIANT=development |
preview | internal | preview | release build for internal testers |
production | store | production | autoIncrement, remote appVersionSource |
npx eas build --profile development --platform ios
npx eas build --profile production --platform all
npx eas submit --profile internal --platform ios --id <build-id>
npx eas submit --profile production --platform iossubmit has two profiles over the same credentials: internal sends a build to TestFlight and the
Play internal track, and production sends it to the Play production track and App Store Connect.
Google Play requires the very first upload of an app to be made by hand in the console.
Every build profile pins node and pnpm to the repository's .node-version and packageManager,
so an EAS worker installs with the same toolchain as local development and CI;
scripts/eas-toolchain.test.ts fails when they drift. Move them together.
Android release builds run R8 minification and resource shrinking through expo-build-properties,
and build only armeabi-v7a and arm64-v8a, the ABIs of physical Android phones; an x86 emulator
needs a development build. A native module that reflects on its own classes can break under R8 only
at runtime, so a release build is the only place to test a new native dependency. The app also
blocks SYSTEM_ALERT_WINDOW, which the dev client adds, and WRITE_EXTERNAL_STORAGE, and the image
picker declares no camera or microphone use, so neither store asks a reviewer to justify a
permission the app never requests. READ_EXTERNAL_STORAGE stays, capped at Android 12, because the
image picker needs it there.
The submit block ships with placeholder credentials. Replace ascAppId, ascApiKeyId,
ascApiKeyIssuerId, and the service-account path with your own, and keep the files under
apps/mobile/credentials/, which is git-ignored. Nothing in this repository holds store
credentials.
Over-the-air updates
An update needs no review and no install step, so its first launch on a user's device is the only
real test it gets. Never publish with a bare eas update: it does not read a build profile's inline
env, so a hand-run publish can ship a bundle pointed at the wrong API.
cd apps/mobile
EXPO_PUBLIC_API_URL=https://api.example.com pnpm ota "fix: what changed"
EXPO_PUBLIC_API_URL=https://api.example.com pnpm ota "fix: ..." --dry-runscripts/ota-publish.mjs refuses a dirty tree, requires an https API URL, asserts
runtimeVersion.policy is still appVersion, runs typecheck and tests, exports the bundle under
the pinned environment, and publishes that export with --skip-bundler at a 25% rollout by default.
The published bundle is Hermes bytecode, whose strings a text scan cannot read, so the API URL is
asserted against a plain-JavaScript export of the same source under the same environment. Both
exports pass --clear, because Metro's cache key does not include EXPO_PUBLIC_* and a warm cache
can otherwise serve bytes built with a different API URL.
The script also refuses to publish without EXPO_PUBLIC_SENTRY_DSN, because a missing DSN turns
crash reporting off on every device that takes the update; pass --without-crash-reporting when the
app has none. It pins EXPO_PUBLIC_APP_ENV to the target branch.
Only publish an update to a runtime version that already has a store build. A native change, from a
new native dependency to a config plugin option, needs a new app version and a store build; never
send it to an older binary as an update. --rollout-percentage 100 is for a hotfix, not for a
routine change.
Extension points left open
In-app purchases are deliberately absent. packages/billing stays provider-neutral subscription
state, and store billing is a separate reviewed provider decision with its own entitlement, restore,
and receipt-validation contract. A production reference for the client architecture is Ritua's
lib/purchases.ts: a single module owning SDK configuration, the entitlement check, and a cached
offline entitlement, with every other module reading a derived boolean. Adding it here means adding
a billing provider, not adding a screen.
Verification before release
Structural checks cannot prove a mobile release. Before shipping:
- complete a real magic-link sign-in on a physical device, from the email client, and confirm a protected route loads;
- confirm Google sign-in returns to the app if the deployment enables it;
- register for push, deliver a real notification, tap it, and confirm the routing;
- sign out and confirm the device stops receiving notifications;
- check light and dark appearance, a narrow device, and the largest system font size;
- install the previous store build and publish an update to it to prove the runtime version pairs;
- install the release candidate over the previous store build without deleting it, from the
internalsubmit track, and confirm the session, preferences, and push registration survive; - trigger a test crash in a
previewbuild with a DSN and confirm it arrives symbolicated.