Aller au contenu principal
HeartCoHeartCo/Documentation
FREN

Field App Setup (Mobile)

Pro tier — The field app is an Expo (React Native) application for on-site interventions, reports and equipment checks.

Prerequisites

  • Node.js ≥ 22
  • pnpm ≥ 9
  • Expo Go installed on your iOS/Android device (for development)
  • A free Expo account on expo.dev (required for EAS builds)

Quick setup

1. Environment variables

cp apps/app-terrain/.env.example apps/app-terrain/.env.local

Fill in apps/app-terrain/.env.local:

# URL of your web instance (apps/web)
EXPO_PUBLIC_API_URL=https://your-domain.com
 
# App branding
EXPO_PUBLIC_APP_SLUG=your-slug
EXPO_PUBLIC_APP_NAME="Your Field App"

Local note: To test on a real phone, EXPO_PUBLIC_API_URL must point to your machine's local IP (e.g. http://192.168.1.42:3000), not localhost.

2. Install dependencies

pnpm install

3. Run in development mode

cd apps/app-terrain
pnpm start

Scan the QR code with Expo Go on your phone.

App structure

apps/app-terrain/
├── app/                    # Expo Router routes
│   ├── (auth)/             # Sign-in screens
│   ├── (tabs)/             # Main tab navigation
│   └── interventions/      # Intervention detail and creation
├── components/             # Reusable components
├── lib/                    # Utilities
│   ├── api.ts              # tRPC client
│   ├── auth.ts             # NextAuth session
│   └── sync.ts             # Offline sync
└── store/                  # Global state (Zustand)

Included features

FeatureDetail
AuthenticationEmail/password login + biometrics (Face ID, fingerprint)
InterventionsList, detail, creation, signature
PhotosCapture and annotate photos from the app
Offline modeMutation queue + automatic sync when the network is back
Push notificationsVia Expo Notifications
Field reportsPDF generated server-side

Production build (EAS Build)

Initial configuration (once)

cd apps/app-terrain
npx eas build:configure

This creates or updates eas.json and links the project to your Expo account.

Android build (APK/AAB)

npx eas build --platform android --profile production

iOS build (.ipa)

npx eas build --platform ios --profile production

iOS prerequisite: an Apple Developer account ($99/year) + certificates configured in EAS.

OTA update (without a rebuild)

npx eas update --branch production --message "Update description"

Authentication

The field app uses the same NextAuth sessions as the web interface. The mobile-dedicated API routes live under /api/mobile/* in apps/web.

To create new mobile endpoints, see apps/web/src/app/api/mobile/.

Troubleshooting

Metro bundler won't start

pnpm start --clear

"Network request failed" error on a real phone

Replace localhost with your local IP:

# Find your IP (macOS/Linux)
ifconfig | grep "inet "
# Windows
ipconfig

Then update EXPO_PUBLIC_API_URL=http://192.168.x.x:3000.

Incompatible Expo dependencies after an update

npx expo install --check

TypeScript error in the app

cd apps/app-terrain
pnpm typecheck

Resources