Skip to Content
Settlr

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

apps/mobile/.env.local
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.app

Without 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:mobile

Scan 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 does

pnpm build doesn't build the mobile app. Release APKs are built on GitHub Actions.

Layout

PathContents
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 with StyleSheet and theme tokens, not hex values (the fixed group and avatar fills excepted).
  • Text: use <Text> from @/components/text, not React Native's. Android ignores fontWeight for custom fonts, so Text picks the Geist family for each weight (weight={600}); mono switches 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 in src/app/(tabs)/ and an entry in TABS in tab-bar.tsx.
  • Packages: add them with npx expo install <pkg> in apps/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 with pnpm dev:mobile --clear.

On this page