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

# Running Your App

> Launch your Shipnative app on iOS, Android, or Web

Once you've cloned the repo and run `yarn install`, you're ready to launch! This guide covers iOS, Android, and Web.

> [!TIP]
>
> **Fast path:** You can launch without API keys (mock mode is automatic), but we recommend running `yarn setup` early so you test against your real services.

## Quick Commands

From the `apps/app` directory:

```bash theme={null}
cd apps/app

yarn ios        # iOS Simulator
yarn android    # Android Emulator  
yarn web        # Web Browser (localhost:19006)
```

Or from the monorepo root:

```bash theme={null}
yarn app:ios      # iOS
yarn app:android  # Android
yarn app:web      # Web
```

Your app will use real services if `.env` is configured; otherwise it falls back to mock mode. Add real API keys early for more accurate behavior.

***

## Platform Details

> [accordion] iOS
>
> **Requirements:**
>
> * Xcode installed (latest version recommended)
> * iOS Simulator available
>
> ```bash theme={null}
> cd apps/app
> yarn ios
> ```
>
> **First run takes longer** - Expo needs to build the native iOS project. Subsequent runs are much faster.
>
> **Using a specific simulator:**
>
> ```bash theme={null}
> # List available simulators
> xcrun simctl list devices available
>
> # Run on specific device
> expo run:ios --simulator "iPhone 15 Pro"
> ```

> [accordion] Android
>
> **Requirements:**
>
> * Android Studio installed
> * Android Emulator configured (or physical device)
> * `ANDROID_HOME` environment variable set
>
> ```bash theme={null}
> cd apps/app
> yarn android
> ```
>
> **First run takes longer** - Expo needs to build the native Android project.
>
> **Troubleshooting:**
>
> * Make sure an emulator is running or a device is connected
> * Run `adb devices` to verify your device is recognized

> [accordion] Web
>
> **Fully supported!** Shipnative runs on web via Expo Web and react-native-web.
>
> ```bash theme={null}
> cd apps/app
> yarn web
> ```
>
> Opens at `http://localhost:19006`
>
> **What works on web:**
>
> * All UI components (Unistyles 3.0 supports web)
> * Authentication (Supabase works everywhere)
> * Payments (RevenueCat Web Billing)
> * Analytics (PostHog)
> * Dark mode
> * Responsive design
>
> **Production build:**
>
> ```bash theme={null}
> yarn bundle:web
> ```

***

## Mock Mode vs Real Services

When you run the app without API keys configured, **mock mode activates automatically**:

| Service | Mock Behavior |
| - | - |
| **Auth** | Login/signup works with fake accounts |
| **Payments** | Purchases succeed instantly, toggle Pro status in dev menu |
| **Analytics** | Events logged to console |
| **Errors** | Captured locally, not sent to Sentry |

> [!WARNING]
>
> **We recommend connecting real services early!**
>
> While mocks are convenient for initial exploration, real services behave differently:
>
> * Email confirmation and OAuth require real Supabase
> * Payment flows need RevenueCat products configured
> * Analytics only capture real data with PostHog connected
>
> **Run `yarn setup` to configure services interactively.**

> [!NOTE]
>
> **How to check service status:** Open the Developer Menu (`Cmd+D` on iOS, `Cmd+M` on Android) and check "Service Status".

[Learn more about mock services →](https://docs.shipnative.app/development/mock-services.md)

***

## Developer Menu

Access the dev menu to debug and test:

| Platform | How to Open |
| - | - |
| **iOS Simulator** | `Cmd + D` |
| **Android Emulator** | `Cmd + M` (Mac) or `Ctrl + M` |
| **Physical Device** | Shake the device |
| **Web** | Browser DevTools |

**Useful options:**

* Component Showcase - see all UI components
* Toggle dark/light mode
* Switch between Free/Pro user
* View service status (mock vs real)
* Reload the app

***

## Troubleshooting

> [accordion] Metro bundler won't start
>
> Clear the cache and restart:
>
> ```bash theme={null}
> yarn app:start --clear
> ```
>
> Or kill the process on port 8081:
>
> ```bash theme={null}
> lsof -ti:8081 | xargs kill -9
> ```

> [accordion] iOS build fails
>
> Clean and reinstall CocoaPods:
>
> ```bash theme={null}
> cd apps/app/ios
> rm -rf Pods Podfile.lock
> pod install
> cd ..
> yarn ios
> ```

> [accordion] Android SDK not found
>
> Set your `ANDROID_HOME` environment variable:
>
> ```bash theme={null}
> export ANDROID_HOME=$HOME/Library/Android/sdk
> export PATH=$PATH:$ANDROID_HOME/platform-tools
> ```
>
> Add this to your `~/.zshrc` or `~/.bashrc`.

> [accordion] Hot reload not working
>
> 1. Open the dev menu
> 2. Ensure "Fast Refresh" is enabled
> 3. If still not working, restart Metro: `yarn app:start --clear`

***

## Next Steps

> [card] [Project Structure](https://docs.shipnative.app/getting-started/project-structure.md)
>
> Understand where things live in the codebase

> [card] [Start Building](https://docs.shipnative.app/getting-started/quickstart.md)
>
> Build features with AI assistance


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