> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Setup

> Set up your development environment for the Soundcheck mobile app

This guide covers the general setup process for developing the Soundcheck mobile app.

## Quick start

**1. Clone the repository**

```bash theme={null}
git clone <repository-url>
cd soundcheck-mobile-app
```

**2. Install dependencies**

```bash theme={null}
npm install
```

**3. Configure environment**

```bash theme={null}
cp .env.example .env
```

Edit `.env` and add your Clerk key:

```env theme={null}
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
```

**4. Start development server**

```bash theme={null}
npm start
```

***

## Development options

### Option 1: Expo Go (fastest)

Use the Expo Go app for quick development without building native code.

```bash iOS theme={null}
# Start server and press 'i' for iOS
npm start
```

```bash Android theme={null}
# Start server and press 'a' for Android
npm start
```

> [!NOTE]
>
> Some features (SecureStore, push notifications) have limited support in Expo Go. Use a development build for full functionality.

### Option 2: Development build (recommended)

Build a native development client for full feature support.

```bash theme={null}
# Create development builds
npx eas build --profile development --platform ios
npx eas build --profile development --platform android
```

### Option 3: Dev container

Use a pre-configured development environment in VS Code/Cursor:

1. Install the Dev Containers extension
2. Open the repository in VS Code/Cursor
3. Press `Cmd+Shift+P` → "Dev Containers: Reopen in Container"
4. Run `npm start` inside the container

> [!WARNING]
>
> Dev Containers don't support physical device USB connections. Use Expo Go on your device or `npm run web` for testing.

***

## Native project generation

The `ios/` and `android/` directories are **not committed** to the repository. Generate them locally when needed:

```bash theme={null}
# Generate iOS native project (macOS only, requires Xcode)
npx expo prebuild --platform ios --clean

# Generate Android native project
npx expo prebuild --platform android --clean

# Generate both platforms
npx expo prebuild --clean
```

> [!NOTE]
>
> The `--clean` flag removes existing native folders before regenerating. All native configuration comes from `app.config.js`.

***

## Running the app

### On iOS simulator

```bash theme={null}
# Option 1: Through Expo CLI
npm start
# Press 'i' to open iOS Simulator

# Option 2: Direct command
npm run ios
```

### On Android emulator

```bash theme={null}
# Option 1: Through Expo CLI
npm start
# Press 'a' to open Android Emulator

# Option 2: Direct command
npm run android
```

### On physical device

1. Install Expo Go on your device
2. Run `npm start`
3. Scan the QR code with your phone

> [!TIP]
>
> For full native functionality on physical devices, create a development build and install via TestFlight (iOS) or direct APK install (Android).

***

## Development scripts

### Core commands

| Command | Description |
| - | - |
| `npm start` | Start Expo development server |
| `npm run ios` | Run on iOS simulator |
| `npm run android` | Run on Android emulator |
| `npm run web` | Run in web browser |
| `npm i` | Install dependencies |

### Quality checks

| Command | Description |
| - | - |
| `npm run dev` | Type check and start Expo |
| `npm run type-check` | TypeScript type checking |
| `npm run type-check:watch` | Watch mode type checking |
| `npm run lint` | Run oxlint |
| `npm run lint:fix` | Auto-fix linting issues |
| `npm run format` | Format with oxfmt |
| `npm run format:check` | Check formatting with oxfmt |
| `npm run check-all` | Run all checks |

### Build commands

| Command | Description |
| - | - |
| `npm run build:ios` | Build iOS with EAS Build |
| `npm run build:android` | Build Android with EAS Build |
| `npm run submit:ios` | Submit to App Store |
| `npm run submit:android` | Submit to Play Store |

***

## Environment variables

Create a `.env` file in the repository root:

```env theme={null}
# Required
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

# Optional - Local API
EXPO_PUBLIC_API_URL=http://localhost:4000
```

> [!WARNING]
>
> Never commit `.env` files. They are gitignored by default.

***

## Troubleshooting

> [accordion] Metro bundler issues
>
> Clear the Metro cache:
>
> ```bash theme={null}
> npx expo start --clear
> ```
>
> Or reset Watchman:
>
> ```bash theme={null}
> watchman watch-del-all
> ```

> [accordion] Dependencies out of sync
>
> Remove and reinstall:
>
> ```bash theme={null}
> rm -rf node_modules package-lock.json
> npm install
> ```

> [accordion] Native modules not found
>
> Regenerate native projects:
>
> ```bash theme={null}
> npx expo prebuild --clean
> ```

> [accordion] Simulator not starting
>
> For iOS, ensure Xcode simulators are installed:
>
> 1. Open Xcode
> 2. Go to **Xcode → Settings → Components**
> 3. Download an iOS Simulator

***

## Next steps

> [card] [iOS Setup](https://docs.soundchecklive.io/engineering/mobile/ios-setup.md)
>
> Detailed iOS development setup

> [card] [Android Setup](https://docs.soundchecklive.io/engineering/mobile/android-setup.md)
>
> Android emulator configuration


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.