Prerequisites

You need a Mac. iOS builds require macOS and Xcode; Android builds also work best on the same machine, so all instructions here assume macOS.

The toolchain (Node, pnpm, Ruby, Java) is managed by mise. Your repo ships a mise.toml that pins the exact versions the app is built with, so you never install Node or pnpm by hand or match version numbers from a doc.

1. Install mise

brew install mise

Activate it in your shell if you haven't before. Follow the activation step for zsh or bash.

2. Install the pinned toolchain

From the root of your cloned repo:

mise trust      # first time only, if prompted
mise install

This reads mise.toml and installs the pinned Node, pnpm, Ruby, and JDK. It also exports the environment the build expects, including ANDROID_HOME pointing at the standard SDK location (~/Library/Android/sdk).

Some repos also define a one-shot task that combines toolchain install with dependency install:

mise run bootstrap

3. iOS: Xcode and CocoaPods

Install Xcode from the Mac App Store and make sure at least one iOS simulator runtime is downloaded (Xcode → Settings → Components). run-ios fails if no iPhone simulator exists. Then accept the license:

sudo xcodebuild -license accept

CocoaPods is installed through Bundler using the Gemfile in your repo. Never install it globally: the repo's Podfile carries patches that only apply through the pinned version. The pnpm run-ios script runs pod install for you; to run it manually:

pnpm pod-install

4. Android: Android Studio and SDK

Install Android Studio from developer.android.com and let it set up the Android SDK at the default location (~/Library/Android/sdk). In SDK Manager, make sure these are installed:

• the SDK Platform matching the repo's compileSdk (currently API 36)
• Platform-Tools (adb) and Build-Tools
• Android Emulator, plus NDK and CMake (the build downloads the pinned NDK if missing)

Accept the SDK licenses (sdkmanager --licenses) and create at least one emulator in Device Manager. You do not need to install a JDK separately; mise pins and installs it.

5. Verify

Inside the repo, every version should resolve to the pinned one:

mise ls           # all tools installed and active
node --version
pnpm --version
ruby --version
java --version

If a command prints a different version than mise.toml pins, mise isn't activated in your shell. Revisit step 1.

Next

• Merchant quickstart — clone and run your store's app
• Partner quickstart — clone and run your host app
• Run on a physical device — when you're ready to test on hardware