# Run your app (/docs/start/run-your-app)



## The run commands [#the-run-commands]

<Tabs items="[&#x22;iOS&#x22;, &#x22;Android&#x22;]">
  <Tab value="iOS">
    ```bash
    pnpm run-ios
    ```

    Installs pods, builds the native app, starts the dev server, and launches
    on a simulator. Pick a specific simulator with:

    ```bash
    pnpm run-ios --simulator="iPhone 17 Pro"
    ```
  </Tab>

  <Tab value="Android">
    Start an emulator from Android Studio's Device Manager (or connect a
    device with USB debugging enabled), then:

    ```bash
    pnpm run-android
    ```

    Whatever device `adb` already sees is used, and the default emulator boots
    if nothing is connected. Force a physical device with `--device` (or
    `--device=<serial>`), an emulator with `--simulator=<avd-name>`.
  </Tab>
</Tabs>

Testing on real hardware, including iPhones (which go through Xcode), is covered in [Run on a physical device](/docs/start/run-on-device).

## What the dev server does [#what-the-dev-server-does]

The run commands start a dev server: a JS bundler that serves the app's JavaScript bundle to the simulator. The native app is built once; after that, edits to TypeScript/JavaScript hot-reload into the running app without rebuilding. You only rebuild the native side when native dependencies change.

If the bundler gets into a stale state (module resolution errors after moving files), restart it with a cache reset:

```bash
pnpm start --reset-cache
```

## The .env file [#the-env-file]

The app is config-driven: which store's screens, blocks, and theme it loads is decided by `.env` in the repo root. Your repo ships with this preconfigured. You don't need to touch it to get running.

```bash title=".env"
ENV=debug
APP_ID="app_XXXXXXXXXXXXX"
APP_NAME="Your Store"
APP_THEME_ID="theme_XXXXXXXXXXXXX"
APP_SERVICE_URL="https://edge.app.appbrew.tech"
```

* `APP_ID` / `APP_THEME_ID` identify the app and theme config to load from the Appbrew backend.
* `APP_SERVICE_URL` is the Appbrew edge API. Don't change it.
* `ENV=debug` loads the editable (non-live) theme you work on in the Appbrew dashboard; `ENV=release` loads the published theme.

**Pointing the app at a different store** means changing `APP_ID` (and `APP_THEME_ID`) to values from that store's Appbrew dashboard, then restarting with `pnpm start --reset-cache` and relaunching. Partner sample apps ship with the demo store's values; merchants get their own store's values preconfigured.

## Common first-run issues [#common-first-run-issues]

* **Nothing launches on iOS** — no simulator matched. Open Xcode's Simulator once so a device exists, or pass `--simulator` explicitly.

* **`run-android` can't find a device** — the emulator isn't running. Start one from Android Studio first.

* **iOS build fails after dependency changes** — pods are stale:

  ```bash
  pnpm clean-ios && pnpm run-ios
  ```

* **Bundler serves stale or missing modules** — watchman and bundler caches: `pnpm start --reset-cache`.

For everything beyond a first run (Gradle failures, Xcode DerivedData, registry 401s), see [Troubleshooting](/docs/ship/troubleshooting).