Run Your Expo App

This guide takes an Expo app you already have and gets it running in Peach, tested and shared. It takes about ten minutes and changes nothing in your app. You need the app’s repository with its dependencies installed, and a terminal.

#1. Install Peach

The installer downloads a standalone peach executable; it needs no Node.js, npm or Bun of its own. Its guided setup installs the runtime and offers the background service, which keeps later commands fast. See Installation to read the script first or pin a version.

#2. Check the app

From your app’s project root, the directory with its package.json and app.json or app.config.ts:

peach doctor

Doctor lists your React and React Native, then every native library with how much of it Peach implements. Look for two marks:

• +
  ? means a library ships native code Peach does not know. Doctor prints a peach.config.ts block that answers it.
• +
  ✗ means a library needs a native SDK Peach cannot run. The line says why and names a replacement when one exists.

If everything reads ✓, ◐ or ·, go on. Otherwise, copy the block doctor printed into a peach.config.ts next to your package.json. For libraries you do not need in the simulator, such as analytics or crash reporting, 'noop' is enough:

// peach.config.ts
import { defineConfig } from 'peachsim/config'

export default defineConfig({
  packages: {
    'react-native-acme-analytics': 'noop',
  },
})

Run peach doctor again until nothing reads ?. Diagnosing your project explains every finding.

#3. Start Expo and open the app

Start your dev server as usual:

npx expo start

In a second terminal, from the same directory:

peach open 8081

Peach opens a simulated iPhone and loads your app from Metro. To try it on Android, or another iPhone, pass a device profile:

peach device list
peach open 8081 --device pixel-8

Because Peach runs the bundle Metro serves, edits you save reach the simulator through Fast Refresh, as they reach a device.

If the app shows an error at startup, run peach doctor again: a native module nothing answers is the most common cause, and doctor names it. For anything else, see Troubleshooting.

#4. Look at the screen

peach describe lists what is on screen: text, buttons, inputs and their test IDs. It is the fastest way to find the selectors your test will use:

peach describe

Take a screenshot when you want to see it:

peach screenshot home.png

#5. Test a flow

Write a Maestro flow against the text and test IDs describe showed. This example taps a Get Started button and checks that Home appears; replace those with your own:

# .maestro/smoke.yaml
- launchApp: {}
- waitFor:
    text: 'Get Started'
    timeout: 10000
- tapOn: 'Get Started'
- assertVisible: 'Home'
- takeScreenshot: home

Run it:

peach maestro test .maestro/smoke.yaml

Peach runs the flow in the simulator you have open and reports each step. If you have no flow yet, peach maestro generate "sign up and reach the home screen" drafts one from a plain-language goal. Testing covers Detox, CI and test results.

#6. Share it

Sign in once, then run the same flow with --preview:

peach login
peach maestro test .maestro/smoke.yaml --preview --preview-open

Peach records the run, uploads your app with it, and prints a /preview/<id> link. Whoever opens it gets your app running live in their browser, next to the recording of the flow. They install nothing and need no TestFlight, dev build or Xcode.

To share without a flow, record what you do by hand:

peach record --mode combined --duration 8 --open

Preview uploads and sharing explains who can open a link and how to change it.

#Next

• +
  The runtime: what keeps moving when your JavaScript blocks, and how Reanimated and gestures run
• +
  Custom stubs: give your own native modules and views real behavior
• +
  Tests in CI: run the same flow on every pull request