Mobile Setup

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

Quick start

Clone the repository

git clone <repository-url>
cd soundcheck-mobile-app

Install dependencies

npm install

Configure environment

cp .env.example .env

Edit .env and add your Clerk key:

EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

Start development server

npm start

Development options

Option 1: Expo Go (fastest)

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

# Start server and press 'i' for iOS
npm start

# Start server and press 'a' for Android
npm start

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.

# 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:

Install the Dev Containers extension
Open the repository in VS Code/Cursor
Press Cmd+Shift+P → “Dev Containers: Reopen in Container”
Run npm start inside the container

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:

# 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

The --clean flag removes existing native folders before regenerating. All native configuration comes from app.config.js.

Running the app

On iOS simulator

# Option 1: Through Expo CLI
npm start
# Press 'i' to open iOS Simulator

# Option 2: Direct command
npm run ios

On Android emulator

# Option 1: Through Expo CLI
npm start
# Press 'a' to open Android Emulator

# Option 2: Direct command
npm run android

On physical device

Install Expo Go on your device
Run npm start
Scan the QR code with your phone

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:

# Required
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

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

Never commit .env files. They are gitignored by default.

Troubleshooting

Metro bundler issues

Clear the Metro cache:

npx expo start --clear

Or reset Watchman:

watchman watch-del-all

Dependencies out of sync

Remove and reinstall:

rm -rf node_modules package-lock.json
npm install

Native modules not found

Regenerate native projects:

npx expo prebuild --clean

Simulator not starting

For iOS, ensure Xcode simulators are installed:

Open Xcode
Go to Xcode → Settings → Components
Download an iOS Simulator

Next steps

iOS Setup

Detailed iOS development setup

Android Setup

Android emulator configuration

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

Quick start

Development options

Option 1: Expo Go (fastest)

Option 2: Development build (recommended)

Option 3: Dev container

Native project generation

Running the app

On iOS simulator

On Android emulator

On physical device

Development scripts

Core commands

Quality checks

Build commands

Environment variables

Troubleshooting

Next steps

iOS Setup

Android Setup

​Quick start

​Development options

​Option 1: Expo Go (fastest)

​Option 2: Development build (recommended)

​Option 3: Dev container

​Native project generation

​Running the app

​On iOS simulator

​On Android emulator

​On physical device

​Development scripts

​Core commands

​Quality checks

​Build commands

​Environment variables

​Troubleshooting

​Next steps

iOS Setup

Android Setup

Quick start

Development options

Option 1: Expo Go (fastest)

Option 2: Development build (recommended)

Option 3: Dev container

Native project generation

Running the app

On iOS simulator

On Android emulator

On physical device

Development scripts

Core commands

Quality checks

Build commands

Environment variables

Troubleshooting

Next steps