tabby-mobile

Expo / React Native client for the Tabby group-travel expense tracker. See ../docs/PRD.md for the product spec and ../docs/design/ for the UI system the screens target.

Stack

• Expo SDK 54, React Native 0.81, React 19
• Expo Router v6 (file-based routing)
• TypeScript (strict)
• NativeWind v4 (Tailwind for React Native)
• TanStack Query v5 (server state)
• Zustand v5 (client state, secured with expo-secure-store)
• Axios (HTTP)
• React Hook Form + Zod (forms & validation)
• lucide-react-native (icons)

Quickstart

cp .env.example .env
# (optional) edit API_BASE_URL if your backend isn't on localhost:8080
npm install
npm start

The terminal will show a QR code and shortcut keys: i for iOS, a for Android, w for web.

Pointing at the backend

Where you run the app	API_BASE_URL
iOS simulator / Web	http://localhost:8080/api/v1
Android emulator	http://10.0.2.2:8080/api/v1
Physical device	http://<your-LAN-ip>:8080/api/v1

Layout

app/                Expo Router routes
  (auth)/             login, register
  (tabs)/             trips, profile
  trip/new.tsx        create trip
  trip/[id]/          expenses, balances, settle, members, settings
  trip/[id]/expense/  new + [expenseId]
  trip/[id]/pay/      [settlementId]
src/
  api/              TanStack Query hooks (axios under the hood)
  components/       reusable UI primitives (Avatar, Money, Card, …)
  stores/           auth + secure-store persistence
  theme/            tokens + ThemeContext
  utils/            formatters, hashes
  types/            shared domain types
global.css          Tailwind directives — imported once in app/_layout.tsx

Linting

npm run lint

Receipt scanning (development build required)

The receipt scanner uses @react-native-ml-kit/text-recognition, which ships native code that Expo Go doesn't bundle. Running OCR therefore needs a custom development build (one-off setup; afterwards npm start works exactly like before, you just open the Tabby dev client instead of Expo Go).

One-time setup

# 1. Generate the native ios/ + android/ projects from app.config.ts.
#    Re-run this whenever you change app.config.ts plugins or version.
npx expo prebuild

# 2a. Build & install the dev client on the iOS simulator (or a tethered
#     iPhone with `--device`). Requires Xcode + CocoaPods.
npx expo run:ios

# 2b. Or for Android — requires Android Studio / SDK on PATH and either
#     an emulator running or a USB-tethered device with USB debugging on.
npx expo run:android

The first build is slow (Xcode/Gradle warm-up); subsequent dev iterations go through the regular npm start Metro bundler against the installed client.

What works in plain Expo Go

Everything except the Scan receipt flow inside Add Expense. The button itself appears, but tapping it on Expo Go will throw because the native module isn't linked. All other features (auth, trips, expenses, splits manually, balances, settle, push) keep working in Expo Go for quick UI iteration.

Cloud builds (no local Xcode/Android Studio)

If you'd rather build in the cloud, EAS Build does the same prebuild + native compile and gives you an installable artifact:

npm i -g eas-cli
eas login
eas build --profile development --platform ios       # or android

Profile config lives in eas.json (create on first run with eas build:configure).