Touli Docs

Appearance

📱 Mobile Development Setup Guide ​

Stack: React Native 0.81 · Expo SDK 54 · Expo Router · NX Monorepo
Package manager: Yarn 1.x
App bundle ID: com.touli.development (dev) · com.touli (prod)

📋 Table of Contents ​

Prerequisites ​

Install these tools before anything else.

Both Platforms ​

ToolVersionInstall
Node.js18+nodejs.org
Yarn1.22+npm install -g yarn
GitLatestgit-scm.com
bash
# Verify versions
node -v
yarn -v
git --version

Environment Setup ​

Android Environment ​

1 — Install JDK 17 ​

powershell
# Windows — via winget
winget install Microsoft.OpenJDK.17

# macOS — via Homebrew
brew install --cask temurin@17

Set environment variables (Windows — run in new terminal after install):

powershell
# Windows (PowerShell — set permanently)
[System.Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Microsoft\jdk-17.0.19.10-hotspot", "User")
bash
# macOS/Linux — add to ~/.zshrc or ~/.bashrc
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

Verify:

bash
java -version
# Expected: openjdk version "17.x.x"

2 — Install Android Studio ​

Download: developer.android.com/studio

During setup, install:

  • ✅ Android SDK
  • ✅ Android SDK Platform (API 35)
  • ✅ Android Virtual Device (AVD)

3 — Set Android SDK Environment Variables ​

Windows:

powershell
[System.Environment]::SetEnvironmentVariable("ANDROID_HOME", "$env:LOCALAPPDATA\Android\Sdk", "User")
# Add platform-tools to PATH
$current = [System.Environment]::GetEnvironmentVariable("PATH", "User")
[System.Environment]::SetEnvironmentVariable("PATH", "$current;$env:LOCALAPPDATA\Android\Sdk\platform-tools", "User")

macOS/Linux — add to ~/.zshrc or ~/.bashrc:

bash
export ANDROID_HOME=$HOME/Library/Android/sdk          # macOS
# export ANDROID_HOME=$HOME/Android/Sdk               # Linux

export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/emulator

Then reload:

bash
source ~/.zshrc   # or source ~/.bashrc

Verify:

bash
adb devices
# Expected: List of devices attached (empty list is fine, means it's working)

iOS Environment ​

macOS only — iOS development requires a Mac with Xcode.

1 — Install Xcode ​

Install from the Mac App Store (free, ~14 GB).

Then install command-line tools:

bash
xcode-select --install
sudo xcodebuild -license accept

2 — Install CocoaPods ​

bash
sudo gem install cocoapods
# or via Homebrew
brew install cocoapods

Verify:

bash
pod --version
# Expected: 1.x.x

3 — Install iOS dependencies ​

bash
cd apps/mobile/ios
pod install
cd ../../..

Running the App ​

⚠️ First time only: You must build the native app before using the Metro dev server.
After the first build, you only need yarn dev:mobile:expo for JS changes.

Android Emulator ​

Step 1 — Create a Virtual Device (AVD) ​

  1. Open Android Studio
  2. Go to Device Manager → Create Device
  3. Choose a device (e.g. Pixel 8) → Select API 35 system image → Finish
  4. Click ▶ to start the emulator

Step 2 — Build & Install (first time) ​

bash
yarn android

This compiles the native Android app and installs the com.touli.development APK on the running emulator. Takes ~3–5 minutes on first run.

Step 3 — Start Dev Server (daily use) ​

bash
yarn dev:mobile:expo

The app will open automatically. Press a to open on Android if it doesn't.

Android Physical Device ​

Step 1 — Enable Developer Mode on your phone ​

  1. Go to Settings → About Phone
  2. Tap Build Number 7 times
  3. Go back to Settings → Developer Options
  4. Enable USB Debugging

Step 2 — Connect via USB ​

bash
adb devices
# Expected output:
# List of devices attached
# XXXXXXXXXX    device

If it shows unauthorized, unlock your phone and tap Allow on the USB debugging prompt.

Step 3 — Build & Install ​

bash
yarn android

Step 4 — Start Dev Server ​

bash
yarn dev:mobile:expo

💡 Wireless debugging (Android 11+): In Developer Options, enable Wireless debugging, then use adb pair and adb connect to go cable-free.

iOS Simulator ​

Step 1 — Open a Simulator ​

bash
# List available simulators
xcrun simctl list devices available

# Open Simulator app (picks a default device)
open -a Simulator

Or launch from Xcode → Xcode menu → Open Developer Tool → Simulator.

Step 2 — Build & Install (first time) ​

bash
yarn ios

This compiles the native iOS app and installs it on the running simulator. Takes ~5–8 minutes on first run.

Step 3 — Start Dev Server (daily use) ​

bash
yarn dev:mobile:expo

Press i to open on iOS if it doesn't launch automatically.

iOS Physical Device ​

Step 1 — Connect your iPhone via USB ​

Step 2 — Trust the computer ​

Unlock your phone and tap Trust when prompted.

Step 3 — Register your device in Xcode ​

  1. Open apps/mobile/ios/mobile.xcworkspace in Xcode
  2. Go to Signing & Capabilities
  3. Select your Team (Apple ID — free account works for dev)
  4. Xcode will register your device automatically

Step 4 — Build & Install ​

bash
yarn ios --device

If you have multiple devices, Xcode will prompt you to choose.

Step 5 — Start Dev Server ​

bash
yarn dev:mobile:expo

Daily Development Workflow ​

Once the native app is installed, your everyday workflow is just:

bash
# Start Metro bundler — hot reload works automatically
yarn dev:mobile:expo
KeyAction
aOpen on Android
iOpen on iOS
rReload app
mToggle dev menu
jOpen debugger
wOpen in browser
Ctrl+CStop server

When to re-run the full build ​

Re-run yarn android / yarn ios only when:

  • ✅ You install a new native package (e.g. react-native-camera)
  • ✅ You change app.json native config (icons, permissions, plugins)
  • ✅ You pull changes that modified android/ or ios/ folders
  • ✅ Native build errors that Metro can't resolve

Troubleshooting ​

❌ JAVA_HOME is not set ​

bash
# Check if Java is installed
java -version

# Windows — set JAVA_HOME (replace version number as needed)
[System.Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Microsoft\jdk-17.0.19.10-hotspot", "User")
# Then restart terminal

❌ No development build installed ​

You're running yarn dev:mobile:expo before building the native app. Run the full build first:

bash
yarn android   # for Android
yarn ios       # for iOS

❌ adb: command not found ​

bash
# Windows — add platform-tools to PATH
$current = [System.Environment]::GetEnvironmentVariable("PATH", "User")
[System.Environment]::SetEnvironmentVariable("PATH", "$current;$env:LOCALAPPDATA\Android\Sdk\platform-tools", "User")
# Restart terminal
bash
# macOS
export PATH=$PATH:$HOME/Library/Android/sdk/platform-tools

❌ Gradle build failed (Android) ​

bash
# Clean Gradle cache and rebuild
cd apps/mobile/android
./gradlew clean        # macOS/Linux
gradlew.bat clean      # Windows
cd ../../..
yarn android

❌ CocoaPods error (iOS) ​

bash
cd apps/mobile/ios
pod deintegrate
pod install
cd ../../..
yarn ios

❌ Metro bundler cache issues ​

bash
yarn dev:mobile:expo --clear
# or
npx expo start --clear

❌ Device not detected by adb ​

  1. Check USB cable (use data cable, not charge-only)
  2. Try a different USB port
  3. Revoke USB debugging authorizations and re-authorize
bash
adb kill-server
adb start-server
adb devices

Quick Reference ​

bash
# ─── First time setup ───────────────────────────────
yarn install                  # Install all dependencies
yarn android                  # Build & install Android dev client
yarn ios                      # Build & install iOS dev client

# ─── Daily development ──────────────────────────────
yarn dev:mobile:expo          # Start Metro + hot reload

# ─── Utilities ──────────────────────────────────────
adb devices                   # List connected Android devices
xcrun simctl list devices     # List iOS simulators (macOS)
cd apps/mobile/android && gradlew.bat clean  # Clean Android build (Windows)
cd apps/mobile/android && ./gradlew clean    # Clean Android build (macOS)

iOS Release Runbook ​

For TestFlight/release flow (versioning, archive steps, smoke tests, and crash triage), see: