> ## 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.
</Tip>

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

<AccordionGroup>
  <Accordion title="iOS" icon="apple">
    **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>

  <Accordion title="Android" icon="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>

  <Accordion title="Web" icon="globe">
    **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
    ```
  </Accordion>
</AccordionGroup>

***

## 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.**
</Warning>

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

[Learn more about mock services →](/development/mock-services)

***

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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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`
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Project Structure" icon="folder-tree" href="/getting-started/project-structure">
    Understand where things live in the codebase
  </Card>

  <Card title="Start Building" icon="bolt" href="/getting-started/quickstart">
    Build features with AI assistance
  </Card>
</CardGroup>