Skip to Content
SsuperslateDocs

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 forWhat to obtain
Anything at allNode, Bun, and either an iOS simulator (Xcode) or an Android emulator
Any build, update, or pushAn Expo account, then npx eas init inside apps/mobile to claim a project ID
Shipping to the App StoreAn Apple Developer Program membership and an App Store Connect app record
Shipping to Google PlayA Google Play Console developer account and an app record
Google sign-in on nativeThe existing Google OAuth web client — see below
Push on iOSAn APNs key, uploaded to EAS credentials
Push on AndroidAn 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

ConcernChoice
RuntimeExpo SDK 58, React Native 0.88, React 19.3, new architecture
Navigationexpo-router with typed routes and Stack.Protected guards
Stylingreact-native-unistyles 3, themed on the shared web design tokens
Motionreact-native-reanimated 4 with react-native-worklets
DataTanStack Query over hc<AppType>(), no client-side cache of server rows
Formsreact-hook-form with the packages/contracts Zod schemas
AuthBetter Auth through @better-auth/expo and expo-secure-store
Lists@legendapp/list
Keyboardreact-native-keyboard-controller
Crashes@sentry/react-native, crash and error reports only, off without a DSN
Iconsphosphor-react-native, imported per icon from phosphor-react-native/src/icons/*

Metro does not tree-shake, so a named import from the phosphor-react-native barrel would bundle every icon. Import each icon directly from phosphor-react-native/src/icons/<Name> (mapped in apps/mobile/tsconfig.json to the package's per-icon declaration files) instead of the barrel.

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 Bun 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 why metro.config.js sets no watchFolders or resolver.nodeModulesPaths. It only starts from Sentry's Expo config, which stamps Debug IDs on release bundles and source maps, and drops console.log, console.debug, and console.info from production bundles while keeping warn and error;
  • Bun's isolated node_modules (its default for workspaces) works. A hoisted layout is 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 detection bun run knip relies on.

If a native build ever fails to resolve a module through Bun's isolated links, that fallback is the escape hatch — set linker = "hoisted" under [install] in bunfig.toml, 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

VariablePurpose
EXPO_PUBLIC_API_URLBase URL of the API. Defaults to http://localhost:8000 when unset.
APP_VARIANTdevelopment 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 bun run version:sync inside apps/mobile.

Local development

The repository owner starts development servers. With the API and database already running:

bun run dev:mobile

That 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
bun run ios
bun run android

Point 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 bun run dev:mobile

Verification commands:

cd apps/mobile
bun run typecheck
bun run test
bun run doctor
bun run prebuild

typecheck and test also run in the repository-wide vp run -r typecheck and bun run test, and bun run 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 bun run build:mobile, and CI runs the same export once per platform, in parallel, whenever apps/mobile exists, so a change that breaks Metro resolution or a Babel plugin fails before a release build does.

The bun test 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 useAnimatedTheme from react-native-unistyles/reanimated, never through UnistylesRuntime.getTheme() or a captured useUnistyles() theme.
  • Call back into JavaScript with scheduleOnRN from react-native-worklets, not runOnJS.
  • Never call an animated ref (ref()) inside a worklet. Since Reanimated 4.7 it is a shareable {value} on the UI runtime and throws Object is not a function. Pass it to measure or scrollTo, which handle an unmounted view themselves.
  • Do not give the child of an animated view flex: 1 along 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 secret

Reports 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
bun run theme:generate

constants/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.ts configures expoClient with expo-secure-store;
  • lib/api-client.ts is the single place the stored session is replayed, as a Cookie header plus the expo-origin header the server's origin check accepts;
  • lib/deep-links.ts owns callback parsing and refuses a link from any other scheme.

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.com

That 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:

PathContents
/.well-known/apple-app-site-associationapplinks with appIDs of <TeamID>.<bundleIdentifier>, served as application/json with no .json extension
/.well-known/assetlinks.jsondelegate_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/devices registers or rotates a device token, GET /push/devices lists them, and DELETE /push/devices revokes 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;
  • notifyUser delivers through the push channel when the user's preference for that notification type allows it, and a token the provider reports as DeviceNotRegistered is deleted.

Deployment:

PUSH_NOTIFICATIONS_ENABLED=true
EXPO_PUSH_ACCESS_TOKEN=      # only when the Expo project enforces push security

While 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 JSON

Without 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_ID and GOOGLE_CLIENT_SECRET on the API;
  • keep SERVER_URL/auth/callback/google as 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:

ProfileDistributionChannelNotes
developmentinternaldevelopmentdev client, APP_VARIANT=development
previewinternalpreviewrelease build for internal testers
productionstoreproductionautoIncrement, 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 ios

submit 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 bun to the repository's .node-version and .bun-version, 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 bun run ota "fix: what changed"
EXPO_PUBLIC_API_URL=https://api.example.com bun run ota "fix: ..." --dry-run

scripts/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 internal submit track, and confirm the session, preferences, and push registration survive;
  • trigger a test crash in a preview build with a DSN and confirm it arrives symbolicated.

On this page