SkillSpark Mobile Environment Setup

Objective

Set up your local development environment to run the Skillspark mobile app on both iOS and Android platforms.

Please follow these steps to set everything up so that we can have a smooth mobile dev experience

Prerequisites

• Bun package manager installed
• Access to the Skillspark monorepo
• Note: macOS is required for iOS Simulator. Non-Mac users can test on physical iPhone devices.

Setup Instructions

1. Clone and Install Dependencies

cd frontend
bun install

2. iOS Setup

Option A: macOS Users - iOS Simulator

Install Xcode:

1. Install Xcode from the Mac App Store (this will take a while - it's ~15GB)
2. Open Xcode and accept the license agreement
3. Install Command Line Tools:

   xcode-select --install

Install iOS Simulator:

1. Open Xcode
2. Go to Xcode → Settings → Platforms
3. Click the + button and install the latest iOS simulator

Verify Setup:

cd apps/mobile
bun ios

The iOS Simulator should launch and the app should load.

Option B: Windows/Linux Users - Physical iPhone Device

Install Expo Go on your iPhone:

1. Download Expo Go from the App Store
2. Make sure your iPhone and computer are on the same WiFi network

Run the app:

cd apps/mobile
bun start

Connect your iPhone:

1. Scan the QR code displayed in terminal using your iPhone's Camera app
2. It will open in Expo Go
3. The app will load and hot reload as you make changes

Note: You won't be able to build standalone iOS apps or test native modules without macOS, but you can develop and test 95% of features this way.

3. Android Setup

Install Android Studio:

1. Download and install Android Studio from https://developer.android.com/studio
2. During installation, make sure to install:
   • Android SDK
   • Android SDK Platform
   • Android Virtual Device (AVD)

Configure Environment Variables:

macOS/Linux - Add to your ~/.zshrc or ~/.bash_profile:

export ANDROID_HOME=$HOME/Library/Android/sdk  # macOS
# export ANDROID_HOME=$HOME/Android/Sdk  # Linux
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools

Windows - Add to System Environment Variables:

ANDROID_HOME=C:\Users\YourUsername\AppData\Local\Android\Sdk
Path=%Path%;%ANDROID_HOME%\emulator;%ANDROID_HOME%\platform-tools

Then reload your terminal (or restart it).

Create an Android Emulator:

1. Open Android Studio
2. Click More Actions → Virtual Device Manager
3. Click Create Device
4. Select Pixel 6 (or any modern device)
5. Click Next
6. Select a system image (recommend API 33 - Android 13)
   • Click Download if not already installed
7. Click Next → Finish

Verify Setup:

# Start the emulator
# Either with a command with the emulator name or manually from android studio
emulator -avd Pixel_6_API_33 & ## use the name of your emulator

# In a new terminal, run the app
cd apps/mobile
bun android

4. Alternative: Physical Device Testing (All Platforms)

For quick testing without emulators:

1. Install Expo Go on your phone:

   • iOS: App Store
   • Android: Google Play Store

2. Ensure your phone and computer are on the same WiFi network

3. Run the app:

   cd apps/mobile
   bun start

4. Scan the QR code with:
   • iOS: Camera app → opens in Expo Go
   • Android: Expo Go app → tap "Scan QR Code"

Verification Checklist

Mac Users:

• iOS Simulator launches and app loads successfully
• Android Emulator launches and app loads successfully
• Hot reload works on both platforms (make a small change and save)
• No TypeScript errors in your IDE

Windows/Linux Users:

• Android Emulator launches and app loads successfully
• Physical iPhone (with Expo Go) connects and loads app successfully
• Hot reload works on both platforms
• No TypeScript errors in your IDE

Common Issues

"Command not found: emulator"

• Make sure you've added Android SDK to your PATH and reloaded your shell/terminal

"No Android connected device found"

• Start the emulator first before running bun android
• Check running emulators: adb devices

iOS Simulator won't launch (Mac only)

• Try: sudo xcode-select --reset
• Restart your computer

Can't connect physical device to Expo

• Ensure phone and computer are on the same WiFi network
• Try using tunnel mode: bun start --tunnel
• Check that your network allows device communication (not on guest network)

Metro bundler cache issues

cd apps/mobile
bun start --clear

Windows: Android Studio can't find SDK

• Make sure ANDROID_HOME path uses backslashes: C:\Users\...\Android\Sdk
• Run Android Studio as Administrator

Platform-Specific Notes

macOS

• ✅ Can develop for iOS and Android
• ✅ Full native module support
• ✅ Can build standalone apps for both platforms

Windows/Linux

• ✅ Can develop for Android (full support)
• ⚠️ iOS development requires physical device + Expo Go
• ❌ Cannot build standalone iOS apps (requires macOS)
• 💡 95% of features testable via Expo Go on iPhone

Getting Help

If you encounter issues:

1. Check the error message carefully
2. Search the Expo documentation
3. Ask in slack