# Running the App

This guide covers how to run OrchardGo on iOS and Android platforms.

## Quick Start

The simplest way to start the app:

```bash
# Start with default configuration (iOS, Orchard brand, Production)
yarn start

# Start iOS
yarn start:ios

# Start Android
yarn start:android
```

## Full Command Options

For more control, use the full command with options:

```bash
yarn start --platform [PLATFORM] --brand [BRAND] --env [ENV] --device [DEVICE]
```

### Parameters

#### Platform
- `ios` - Run on iOS simulator/device
- `android` - Run on Android emulator/device

#### Brand
- `orchard` - Orchard branded app
- `awal` - Awal branded app

#### Environment
- `prod` - Production environment
- `qa` - QA/staging environment

#### Device (Optional)
- Device name or ID
- Use quotes for names with spaces: `--device "iPhone 15 Pro"`

### Examples

```bash
# Run Orchard iOS app in QA environment
yarn start --platform ios --brand orchard --env qa

# Run Awal Android app in Production
yarn start --platform android --brand awal --env prod

# Run on specific iOS device
yarn start --platform ios --device "iPhone 15 Pro Max"

# Run on specific Android emulator
yarn start --platform android --device Pixel_5_API_34
```

## iOS Development

### List Available Simulators

```bash
yarn ios:simulators
```

This shows all iOS simulators with their UUIDs and status.

### Run on Specific Simulator

```bash
# Using UUID
yarn ios:simulator:run 12345678-2345-1234-1234-123456789012

# Using device name (via start command)
yarn start --platform ios --device "iPhone 15"
```

### Open in Xcode

```bash
yarn xcode
```

This opens the workspace in Xcode for advanced debugging and configuration.

### Common iOS Simulators

- `iPhone 15 Pro Max`
- `iPhone 15 Pro`
- `iPhone 15`
- `iPhone 14`
- `iPad Pro (12.9-inch)`

## Android Development

### List Available Devices and Emulators

```bash
# List connected physical devices
yarn android:devices

# List available emulators
yarn android:emulators
```

### Run on Emulator

```bash
# Start a specific emulator
yarn android:emulator:run Medium_Phone_API_34

# Then run the app
yarn start:android
```

### Prepare Physical Device

```bash
# Enable USB debugging and install necessary tools
yarn android:device:prepare
```

### Common Android Emulators

- `Pixel_5_API_34`
- `Pixel_7_Pro_API_34`
- `Medium_Phone_API_34`
- `Nexus_5X_API_34`

## Metro Bundler

React Native uses Metro bundler to compile JavaScript. It starts automatically with `yarn start`.

### Metro Commands

```bash
# Reset Metro cache
yarn reset

# Start with clean cache
yarn start --reset-cache
```

### Metro Troubleshooting

If you encounter bundler issues:

1. **Kill existing Metro processes**:
   ```bash
   yarn reset
   ```

2. **Clear watchman cache**:
   ```bash
   watchman watch-del-all
   ```

3. **Clear Metro cache**:
   ```bash
   rm -rf $TMPDIR/metro-*
   ```

4. **Complete clean**:
   ```bash
   yarn clean
   yarn install
   ```

## Development Workflow

### Hot Reloading

React Native supports hot reloading for instant updates:

1. **iOS Simulator**: Press `Cmd + D` → Enable Hot Reloading
2. **Android Emulator**: Press `Cmd + M` (macOS) or `Ctrl + M` (Windows) → Enable Hot Reloading

### Developer Menu

Access the developer menu for debugging tools:

- **iOS Simulator**: `Cmd + D`
- **Android Emulator**: `Cmd + M` (macOS) or `Ctrl + M` (Windows)
- **Physical Device**: Shake the device

### Debug Options

From the developer menu:
- **Reload** - Reload JavaScript bundle
- **Enable Hot Reloading** - Auto-reload on save
- **Enable Live Reload** - Full reload on save
- **Toggle Inspector** - Inspect element hierarchy
- **Show Performance Monitor** - View FPS and memory

## Running with Different Configurations

### Production Build on Device

```bash
# iOS Production build
yarn start --platform ios --env prod --configuration Release

# Android Production build
yarn start --platform android --env prod --variant release
```

### Debug vs Release

- **Debug**: Includes development tools, slower performance
- **Release**: Optimized, no dev tools, production-like performance

## Environment Variables

The app loads environment variables from `.env` during build. To change environments:

1. Update `.env` file
2. Clean and reinstall:
   ```bash
   yarn clean
   yarn install
   ```
3. Restart the app

## Multiple Device Testing

### iOS: Run on Multiple Simulators

```bash
# Terminal 1
yarn start --platform ios --device "iPhone 15"

# Terminal 2
yarn start --platform ios --device "iPad Pro"
```

### Android: Run on Multiple Emulators

```bash
# Start first emulator
yarn android:emulator:run Pixel_5_API_34

# Start second emulator
yarn android:emulator:run Pixel_7_Pro_API_34

# Run app (it will install on both)
yarn start:android
```

## Troubleshooting

### "Port 8081 already in use"

```bash
# Kill Metro bundler
yarn reset

# Or manually
lsof -ti:8081 | xargs kill
```

### "Build failed" on iOS

```bash
# Clean build folders
cd ios
xcodebuild clean
rm -rf ~/Library/Developer/Xcode/DerivedData

# Reinstall pods
rm -rf Pods Podfile.lock
pod install
```

### "Build failed" on Android

```bash
# Clean Android build
cd android
./gradlew clean

# Clear Gradle cache
rm -rf ~/.gradle/caches
```

### App Won't Install on Device

- Verify device is trusted (iOS)
- Check USB debugging is enabled (Android)
- Ensure bundle ID matches provisioning profile (iOS)
- Verify signing configuration (both platforms)

## Next Steps

- [Testing](./testing.md)
- [Debugging](./debugging.md)
- [Scripts Reference](./scripts-reference.md)