Skip to main content

Mobile App Overview

Complete guide for developing and running the React Native mobile application.

📋 Table of Contents​

⚙️ Starting the Mobile Container​

⚠️ Important: For mobile development, native execution is recommended (without Docker), as it is simpler and faster.

Docker (Metro Bundler + tunnel only)​

# Start container
docker compose --profile mobile up -d mobile

# View logs
docker compose logs -f mobile
cd apps/mobile
pnpm install
pnpm start

📱 Connecting from Phone via Expo Go​

Prerequisites​

Install Expo Go on your phone:

Works from any network, including different WiFi or mobile internet.

# Already configured in docker-compose.yaml with --tunnel flag
docker compose logs mobile  # Find URL like exp://u.expo.dev/...

# Open Expo DevTools for QR code
http://localhost:19000

In the Expo Go app:

  1. Scan the QR code from the browser (localhost:19000)
  2. Or manually enter the URL exp://u.expo.dev/... from logs

Method 2: Local network​

Requires the phone and computer to be on the same WiFi network.

1. Find your machine's IP:

ip addr show | grep "inet " | grep -v 127.0.0.1
# or
ifconfig | grep "inet " | grep -v 127.0.0.1

2. Create a .env file in the project root:

echo "MOBILE_HOST=192.168.0.31" >> .env  # replace with your IP

3. Restart the container:

docker compose --profile mobile down
docker compose --profile mobile up -d mobile

4. In Expo Go enter:

exp://YOUR_IP:8081

📦 Updating Dependencies​

# Recommended to do on the host (not in the container)
cd apps/mobile
pnpm add expo@~54.0.31 expo-constants@~18.0.13

# Restart container
docker compose restart mobile

🔌 Available Ports​

PortPurpose
8081Metro Bundler
19000Expo DevTools (QR code and management)
19001Metro UI
19006Expo Web version

🔍 Debugging the Mobile Container​

Check Metro Bundler​

curl http://localhost:8081/status

Check environment variables​

docker compose exec mobile printenv | grep -E "(EXPO|MOBILE)"

Enter the container​

docker compose exec mobile sh

View Metro logs​

docker compose logs mobile | grep "Metro\|Bundler\|exp://"

Restart with cache clear​

docker compose exec mobile npx expo start --clear

🐛 Common Issues​

Error: "Failed to download remote update"​

Cause: Expo Go cannot download the bundle from Metro Bundler.

Solution:

  • Use tunnel mode (already enabled by default)
  • Or make sure the phone is on the same WiFi network and MOBILE_HOST is set correctly

Error: "ERR_PNPM_UNEXPECTED_STORE"​

Cause: pnpm store conflict between host and container.

Solution:

  • Update packages on the host, not in the container
  • Or rebuild the container: docker compose build --no-cache mobile

QR code doesn't appear​

Solution:

Application won't load​

Solution:

# Check that Metro is running
curl http://localhost:8081/status

# Restart with cache clear
docker compose down
docker compose --profile mobile up -d mobile
docker compose logs -f mobile

📚 Additional Resources​

⚡ Quick Commands​

# Start
docker compose --profile mobile up -d mobile

# Logs
docker compose logs -f mobile

# Stop
docker compose --profile mobile down

# Restart
docker compose restart mobile

# Enter container
docker compose exec mobile sh