Mobile app
The Android app in apps/mobile, built with Expo and Expo Router.
apps/mobile (package mobile) is the Android app: Expo (SDK 58) with
Expo Router, in TypeScript. It's built phase by phase; screens that
aren't built yet show a placeholder. It reuses @settlr/shared (schemas,
money and date formatting) and the Convex api types from
@settlr/backend/convex/_generated/api, and talks to the same Convex
deployment as the web app, so changes on one show up live on the other.
Run it on your phone
Install Expo Go
Install Expo Go from the Play Store. While the app is being built, it runs inside Expo Go, so you don't need Android Studio or an Expo account.
Add apps/mobile/.env.local
Use the same two URLs as apps/web/.env.local, renamed, plus the
deployment's SITE_URL (the web app the app signs in through):
EXPO_PUBLIC_CONVEX_URL=https://<deployment>.convex.cloud
EXPO_PUBLIC_CONVEX_SITE_URL=https://<deployment>.convex.site
EXPO_PUBLIC_SITE_URL=https://<your-site>.vercel.appWithout EXPO_PUBLIC_SITE_URL the app signs in through the
.convex.site URL, where email codes work but Google doesn't.
EXPO_PUBLIC_* values are inlined into the bundle, so restart the dev
server after changing them.
Start the dev server
pnpm dev:mobileScan the QR code with Expo Go. The phone and the computer must be on the
same Wi-Fi; otherwise run pnpm dev:mobile --tunnel.
Sign in
Signed-out people see sign-in.tsx (email, or Continue with Google) and
verify.tsx (the 6-digit code). src/app/_layout.tsx reads the session
with authClient.useSession() and guards the routes with
Stack.Protected: signing in or out flips the guards and the router
moves to the tabs or to sign-in by itself, so screens don't navigate after
it. The session is kept in secure storage, so the app opens signed in.
Authentication covers how it
works on the server.
To sign in from Expo Go, the deployment's TRUSTED_ORIGINS must include
exp:// (the dev deployment's does). Without a real inbox, request a code
for delivered@resend.dev and read it with
pnpm exec convex data --component betterAuth verification in
packages/backend.
Checks
pnpm --filter mobile typecheck # also part of pnpm typecheck
pnpm --filter mobile export:android # bundles the app the way a release build doespnpm build doesn't build the mobile app. Release APKs are built on GitHub
Actions.
Layout
| Path | Contents |
|---|---|
src/app/ | Expo Router routes. _layout.tsx loads the fonts, wraps everything in the Convex and Better Auth provider and guards the signed-in routes; (tabs)/ holds the five tabs, sign-in.tsx and verify.tsx the signed-out screens |
src/components/ | Text (Geist or Geist Mono, coloured from the theme), Button, Screen (a tab's page), AuthScreen (the signed-out frame), TabBar, Brand, line icons, and the temporary account button on Home |
src/theme/ | Tokens from design/DESIGN.md for dark and light (tokens.ts), and useColors() |
src/lib/ | The Convex client (convex.ts) and Better Auth (auth-client.ts: the client and the sign-in actions) |
Imports use the @/ alias for apps/mobile/src.
Conventions
- Design: the Android mockups in
design/screens/android/are the reference. The app follows the phone's light or dark setting (useColors()); dark is the reference theme. Style withStyleSheetand theme tokens, not hex values (the fixed group and avatar fills excepted). - Text: use
<Text>from@/components/text, not React Native's. Android ignoresfontWeightfor custom fonts, soTextpicks the Geist family for each weight (weight={600});monoswitches to Geist Mono with tabular figures for amounts. - Tabs: the bottom bar is
TabBar, a flat bar with a 3 px accent line over the active tab. A new tab needs a route insrc/app/(tabs)/and an entry inTABSintab-bar.tsx. - Packages: add them with
npx expo install <pkg>inapps/mobile, which picks the version that matches the Expo SDK. The app has to keep running in Expo Go, so only use native modules that Expo Go includes. - Metro is configured for the pnpm workspace automatically; there's no
metro.config.js. After adding a workspace package, restart withpnpm dev:mobile --clear.