💻 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.

iOS Simulator (macOS only)

The iOS simulator ships inside Xcode. You only need it on macOS — there's no iOS simulator on Linux/Windows.

1. Install Xcode from the App Store (large download, ~10–15 GB — start early).
2. Install the Command Line Tools so the build toolchain (xcodebuild, git, clang) is on your PATH:

   xcode-select --install

3. Point xcode-select at the full Xcode app (not just the CLT shim) and accept the license:

   sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
   sudo xcodebuild -license accept

4. Install a simulator runtime. Open Xcode → Settings → Components (Xcode 16+; older versions: Settings → Platforms) → download an iOS runtime. The latest is fine.
5. Install the CocoaPods dependency manager (needed for the native iOS build):

   brew install cocoapods

6. Verify the simulator is installed and bootable:

   xcrun simctl list devices available   # lists installed simulators
   open -a Simulator                     # launches the Simulator app

TIP

You don't have to pre-create a device. expo run:ios boots a default iPhone simulator automatically. To pick a specific one: pnpm --filter @tellia-solutions/mobile-app ios --device "iPhone 16 Pro".

Android Emulator (macOS, Linux, Windows)

1. Install Android Studio from developer.android.com/studio.
2. Install the SDK + emulator. On first launch the setup wizard installs the SDK, a system image, and the emulator. To add or change them later: Settings → Languages & Frameworks → Android SDK → SDK Platforms tab (pick API 33+) and SDK Tools tab (ensure Android SDK Command-line Tools, Android Emulator, and Android SDK Platform-Tools are checked).
3. Set ANDROID_HOME and add the tools to your PATH. Add to ~/.zshrc (macOS default shell):

   export ANDROID_HOME="$HOME/Library/Android/sdk"          # macOS path; Linux: $HOME/Android/Sdk
   export PATH="$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin"

   Reload with source ~/.zshrc.
4. Create a virtual device. Android Studio → Device Manager → Create Device → pick a Pixel → choose a system image with API 33+ (download it if prompted) → Finish.
5. Accept the SDK licenses (required before the first Gradle build):

   yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses

6. Verify the toolchain and your virtual device are visible:

   adb --version              # platform-tools on PATH
   emulator -list-avds        # lists the AVD you created

NOTE

Start the emulator from Android Studio's Device Manager (or emulator -avd <name>) before running the app, then run the Android command below.

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....

IMPORTANT

The secret values (Mapbox tokens, Sentry DSN/auth token) live in the 1Password item named Mobile ENV. Copy them from there — don't ask for them in chat or commit them.

TIP

Mapbox: the public token (pk.) goes in EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN; the secret token (sk.) is only used at build time for RNMAPBOX_MAPS_DOWNLOAD_TOKEN. Both are in the Mobile ENV 1Password item.

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