Android Emulator Setup & Running the App

Status: Reference

Status: Active

Layer 2 guide. Read when setting up or troubleshooting the Android emulator.

---

Prerequisites

• Android Studio installed with at least one AVD configured
• JDK 17+ on PATH (java -version)
• adb on PATH (adb version) — ships with Android Studio platform-tools
• Node dependencies installed (npm install)

---

Development Build vs Expo Go

	Expo Go	Development Build
Setup	Zero — just scan QR	One-time npx expo run:android (~5 min)
Native modules	Limited (no Kakao Login)	Full support
Hot reload	Yes	Yes
Use when	Quick prototyping	Kakao Login, any native module

This project uses a development build (expo-dev-client is installed). Expo Go will not work once native modules like Kakao Login are wired up.

---

First-Time Setup (development build)

Build and install the dev client APK onto the emulator once:

# Emulator must be running first
npx expo run:android

This compiles native code (~5 min). After it completes, the twomore app icon appears on the emulator. You only repeat this step when native dependencies change (e.g., adding a new Expo plugin).

---

Daily Workflow

This project runs on WSL2 + Windows Android emulator. Metro runs inside WSL2 but the emulator is on Windows — they can't talk directly. Always use --tunnel.

After the dev client is installed, just start Metro:

# Local Supabase (must be running: npx supabase start)
npx expo start --dev-client --tunnel

Open the app on the emulator — it connects to Metro via tunnel. Hot reload works for all JS/TS changes without rebuilding.

--tunnel routes through ngrok. It's the only reliable option on WSL2 and also works when the phone is not on the same Wi-Fi or connected via USB.

Testing on a physical phone (no USB required)

The same --tunnel command works for physical phones. The phone just needs internet — no USB, no same-network requirement. Scan the QR code in the Expo dev client on the phone.

Testing without Metro (PC off)

Use standalone builds. See builds-and-deployment.md for the full workflow.

---

Managing Multiple Emulators

List available AVDs

emulator -list-avds

Target a specific device

# 1. List running emulators / connected devices
adb devices

# 2. Start a specific AVD (if not already running)
emulator -avd <AVD_NAME> &

# 3. Start Metro — press 'a' in the Expo CLI menu to open on Android
npx expo start --dev-client --tunnel

If you have two emulators running simultaneously, press a in the Expo terminal and select the target device from the list.

Run on a specific device by serial

# Get the serial (e.g., emulator-5554, emulator-5556)
adb devices

# Point Expo to that serial
ADB_DEVICE_SERIAL=emulator-5554 npx expo start --dev-client --tunnel

---

Environment Modes

Mode	Command	Backend
Local Supabase	npx expo start --dev-client --tunnel	http://10.0.2.2:54321
Staging/Prod	Set .env vars, then npx expo start --dev-client --tunnel	Remote Supabase

.env for local Supabase

EXPO_PUBLIC_SUPABASE_URL=http://10.0.2.2:54321
EXPO_PUBLIC_SUPABASE_ANON_KEY=<key from npx supabase status>
EXPO_PUBLIC_KAKAO_APP_KEY=<your key>

Note: emulator uses 10.0.2.2 (not localhost) to reach the host machine.

Start local Supabase first:

npx supabase start        # Start local instance
npx supabase db reset     # Apply migrations + seed
npx expo start --dev-client

---

Two-Device Workflow

# Terminal 1 — start both AVDs
emulator -avd Pixel_7_API_35 &
emulator -avd Pixel_Tablet_API_35 &

# Terminal 2 — start Metro with tunnel
npx expo start --dev-client --tunnel
# Press 'a' → select device from list

Metro broadcasts hot-reload updates to all connected devices via the tunnel automatically.

---

Common Issues

Unable to determine the default URI scheme / expo-dev-client not installed

The dev client APK isn't on the emulator yet. Run:

npx expo run:android

Failed to download remote update

WSL2 networking issue — the emulator (on Windows) can't reach Metro (in WSL2) directly. Always use --tunnel:

npx expo start --dev-client --tunnel

INSTALL_FAILED_UPDATE_INCOMPATIBLE

App signature changed. Uninstall first:

adb uninstall host.exp.exponent   # or your app package if custom build
npx expo run:android

adb: command not found

Add Android platform-tools to PATH in ~/.bashrc or ~/.zshrc:

export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/emulator

Then source ~/.bashrc.

Native module changes not reflected

If you add/remove an Expo plugin or native package, rebuild:

npx expo run:android

JS-only changes never need a rebuild.

Metro bundler port already in use

lsof -ti:8081 | xargs kill -9
npx expo start --dev-client

Emulator slow / low memory

In Android Studio AVD Manager → edit AVD → increase RAM to at least 4096 MB, VM heap to 512 MB.

---

Useful adb Commands

adb devices                          # list connected devices
adb reverse tcp:8081 tcp:8081        # restore Metro tunnel after emulator restart
adb logcat -s ReactNative            # JS console logs
adb logcat -s Expo                   # Expo-specific logs
adb shell input keyevent 82          # open dev menu (replaces shake gesture)
adb shell pm clear host.exp.exponent # clear app data (reset local storage)