Setup

Peach needs no per-app install. You keep starting your app with the command you already use, and Peach connects to that dev server. A plugin and a config file are both optional; add them when you want what they give you.

If you have not installed Peach yet, follow Installation first.

#Expo and bare React Native (Metro)

Start Metro the way you normally do, from your app’s project root:

# Expo
npx expo start

# bare React Native
npx react-native start

Then, from the same directory, open the app in Peach:

peach open 8081

Use your server’s real port. Without a port, peach open scans for running React Native dev servers and lets you pick one, and a bare peach opens the same picker in the simulator.

Run peach open from the project root when you can. Peach reads your app’s configuration from that directory, including your Expo app config, custom fonts, splash screen and icon. It can still load the bundle from elsewhere, but those details may be missing.

#The optional Metro plugin

Peach works with a plain Metro server. Wrapping your Metro config with withPeach() from peachsim/metro adds two things: it embeds Metro’s exact module map in each bundle, so Peach never has to infer which module is which, and it serves the simulator from your Metro server at /__peachsim/.

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config')
const { withPeach } = require('peachsim/metro')

module.exports = withPeach(getDefaultConfig(__dirname))

See Metro plugin for what it changes in your bundles and for its bundle URL helpers.

#One apps

Start your One app with its usual dev command, then open its port:

peach open <port>

To make the simulator available on your One dev server itself, add peachPlugin() from peachsim/vite. It serves Peach at /__peachsim/ and leaves your app code and workflow unchanged:

// vite.config.ts
import { defineConfig } from 'vite'
import { peachPlugin } from 'peachsim/vite'

export default defineConfig({
  plugins: [
    // your One plugins
    peachPlugin(),
  ],
})

See One plugin for its options, including opening the app in its own desktop window.

#Check your project first

Before you open an app for the first time, run:

peach doctor

It reports the React and React Native your app declares, how much of each native library Peach implements, and any native code Peach does not know, with the config that answers it. Diagnosing your project walks through its output.

#peach.config.ts

Most apps need no config. Add a peach.config.ts next to your package.json when you need to answer native code Peach does not know, set environment variables, or pin simulator settings for the app. Peach also accepts peach.config.js, peach.config.mjs and peach.config.cjs.

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

export default defineConfig({
  // native modules and views Peach does not know, keyed by package
  packages: {
    'react-native-acme-analytics': 'noop',
  },
  // process.env values your code reads at runtime
  env: { API_URL: 'http://localhost:3000' },
})

The peach CLI supplies the peachsim/config import when it loads the file, so it works without installing anything. Add peachsim as a dev dependency if you want editor types; peach setup offers to do that for you, along with a peach script in your package.json. Peach reads the file each time it loads your app, so your next reload picks up an edit.

The fields you are most likely to use:

The Configuration guide shows each slot with worked examples, and the PeachConfig reference lists every type.

#Next

• +
  Run your Expo app takes an existing Expo app all the way to a tested, shared preview.
• +
  Wrap an existing app covers apps whose libraries need stubs before they run.