Run your app
Boot the app on a simulator or device and point it at a store.
The run commands
pnpm run-iosInstalls pods, builds the native app, starts the dev server, and launches on a simulator. Pick a specific simulator with:
pnpm run-ios --simulator="iPhone 17 Pro"Testing on real hardware, including iPhones (which go through Xcode), is covered in Run on a physical device.
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:
pnpm start --reset-cacheThe .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.
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_IDidentify the app and theme config to load from the Appbrew backend.APP_SERVICE_URLis the Appbrew edge API. Don't change it.ENV=debugloads the editable (non-live) theme you work on in the Appbrew dashboard;ENV=releaseloads 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
-
Nothing launches on iOS — no simulator matched. Open Xcode's Simulator once so a device exists, or pass
--simulatorexplicitly. -
run-androidcan't find a device — the emulator isn't running. Start one from Android Studio first. -
iOS build fails after dependency changes — pods are stale:
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.