---
name: ios-dev
description: iOS/React Native development with Expo. Use when working on mobile app, running builds, debugging device issues, or setting up development environment including tethering.
---

# iOS Development Guide

## Project Structure

```
mobile/
├── app/                    # Expo Router pages
│   ├── _layout.tsx
│   ├── index.tsx           # Home screen
│   └── room/[id].tsx       # Voice call room
├── src/
│   ├── components/         # UI components
│   ├── hooks/              # Custom hooks (WebRTC, Socket, Speech)
│   └── types/
├── ios/                    # Native iOS project (generated by prebuild)
└── .env                    # Environment variables
```

## Key Commands

```bash
cd mobile

# Development (WiFi - same network as Mac)
npx expo start --dev-client

# Development (Tethering - requires tunnel)
npx expo start --dev-client --tunnel

# Build for specific device
npx expo run:ios --device "DEVICE_NAME"

# Clean rebuild (after config changes)
npx expo prebuild --platform ios --clean

# List available devices
xcrun xctrace list devices
```

## Environment Configuration

```bash
# WiFi development
EXPO_PUBLIC_SIGNALING_SERVER_URL=http://192.168.x.x:3001

# Production (Render server)
EXPO_PUBLIC_SIGNALING_SERVER_URL=https://webrtc-signaling-xxxx.onrender.com
```

## Tethering Development

When Mac is connected to iPhone's Personal Hotspot:

1. **Problem**: iPhone cannot directly access devices on its own hotspot
2. **Solution**: Use ngrok tunnel

```bash
# Install ngrok (first time)
npm install -g @expo/ngrok@^4.1.0

# Start with tunnel
npx expo start --dev-client --tunnel

# Get tunnel URL
curl -s http://127.0.0.1:4040/api/tunnels | grep -o '"public_url":"https://[^"]*"'
```

**Important**: Use **HTTPS** URL (iOS App Transport Security requirement)

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "Device is busy" | Unlock iPhone, reconnect USB |
| Metro connection fails | Check IP address, or use `--tunnel` |
| "main" not registered | Restart Metro with `--clear` |
| Build fails after config change | Run `npx expo prebuild --clean` |
| Simulator no audio | Use real device for audio testing |

## Development Workflow

1. Start signaling server: `cd server && npm run dev`
2. Start Metro: `cd mobile && npx expo start --dev-client`
3. Open app on iPhone, enter Metro URL
4. For code changes: Hot reload automatic
5. For native changes: Rebuild with `npx expo run:ios --device`