💻 Local Dev Setup

Prerequisites

Required Tools

Tool	Purpose	Install
Node.js 24+	Runtime	brew install node or nvm
pnpm	Package manager	brew install pnpm
Xcode (macOS)	iOS simulator	App Store
Android Studio	Android emulator	developer.android.com

NOTE

iOS only runs on macOS. Android can be developed on any platform.

Xcode Setup (iOS)

1. Install Xcode from the App Store
2. Install Command Line Tools: xcode-select --install
3. Open Xcode → Settings → Platforms → install the iOS simulator runtime you want

Android Studio Setup

1. Install Android Studio
2. Open AVD Manager → create a Pixel device with a recent API level (API 33+)
3. Accept Android SDK licenses: yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses

Clone & Install

# From repo root
pnpm install

Environment Variables

Create apps/mobile/.env with the following:

# Backend API endpoint (3888 is the default local port)
EXPO_PUBLIC_API_URL=http://localhost:3888

# Environment (development | staging | production)
EXPO_PUBLIC_ENV=development

# Sentry (optional for local dev)
EXPO_PUBLIC_SENTRY_DSN=
SENTRY_AUTH_TOKEN=
SENTRY_PROJECT=
SENTRY_ORG=

# Mapbox — required to render the map
EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN=pk....
RNMAPBOX_MAPS_DOWNLOAD_TOKEN=sk....

TIP

Get Mapbox tokens from the Mapbox dashboard. The public token (pk.) goes in EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN. The secret token (sk.) is only needed at build time for RNMAPBOX_MAPS_DOWNLOAD_TOKEN.

Firebase Config Files

Firebase native modules require platform-specific config files. These are not committed to the repo — get them from a team member or the Firebase console.

File	Location	Platform
GoogleService-Info.plist	apps/mobile/ios/	iOS
google-services.json	apps/mobile/android/app/	Android

Running the App

iOS Simulator

pnpm --filter @tellia-solutions/mobile-app ios

This runs expo run:ios which triggers a native build (CocoaPods + Xcode). First build takes several minutes.

Android Emulator

Start an emulator from Android Studio AVD Manager first, then:

pnpm --filter @tellia-solutions/mobile-app android

NOTE

On Android, localhost in EXPO_PUBLIC_API_URL is automatically remapped to 10.0.2.2 (the Android emulator's host alias) by the API client.

Dev Server Only (no simulator)

pnpm --filter @tellia-solutions/mobile-app start

Opens the Expo dev server. You'll need an already-built app (physical device or simulator) to connect to it.

Troubleshooting

Symptom	Fix
pod install fails	cd apps/mobile/ios && pod install --repo-update
Metro bundler cache issues	pnpm --filter @tellia-solutions/mobile-app start --clear
Android build fails with SDK error	Check ANDROID_HOME env var is set
Firebase auth errors	Verify GoogleService-Info.plist / google-services.json are present
Map not rendering	Check EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN is set in .env