Configuration

peach.config.ts (or .js) is the per-project, repo-rooted config file that describes how Peach should load your app: which native modules to stub, which env vars to inject, which device/appearance settings to default to, any initial app state, and whether this repo needs a fixed engine version.

Create one

Create peach.config.ts in the repo root only when you need a fixed runtime or advanced module, environment, or simulator overrides. It is not required for normal peach open <port> usage.

In a monorepo, put the config in the app’s own directory, next to that app’s package.json. Peach reads the project root your dev server advertises, or the --project-root you pass to peach open; it never scans workspaces or guesses between apps.

The smallest version selection has no import and does not add Peach to the app’s dependencies:

// peach.config.ts
export default {
runtimeVersion: '0.1.845',
}

Remove the field to follow the current stable runtime. Repos that already have peachsim as a dependency may optionally use defineConfig for editor types, but the standalone CLI does not require a per-app install.

Full reference

export default {
// generic Metro module overrides (matched by path fragment).
modules: {
'react-native-analytics': 'noop', // empty module
'react-native-gesture-handler': false, // disable peach's builtin, use original
'my-native-lib': { use: 'expo-haptics' }, // redirect to an existing compat stub
'my-native-camera': { file: './stubs/camera.ts' },
'react-native-config': {
inline: { API_URL: 'http://localhost:3000', ENV: 'development' },
},
// path-fragment match: this targets a deep file inside a package
'dist/assets/config.json': {
inline: {
/* … */
},
},
},
// native stubs, keyed by the package whose native side they answer. a
// module file default-exports the native module object; a view file
// default-exports the component that renders in the view's place.
packages: {
'react-native-acme-analytics': 'noop', // every native name it asks for is inert
'react-native-keychain': {
modules: { RNKeychainManager: './stubs/keychain.ts' },
},
'my-app': {
views: {
RNBalanceLabel: './peach/BalanceLabel.tsx',
MyModule_ProgressiveBlurView: './peach/ProgressiveBlur.tsx',
},
},
},
// env vars (process.env.*), see "Env caveat" below.
env: { API_URL: 'http://localhost:3000', DEBUG: 'true' },
// simulator settings (CLI flags override these per invocation).
settings: { deviceModel: 'iphone-16-pro', colorScheme: 'dark' },
// initial app state passed to the simulator.
initialState: {
authenticated: false,
locale: 'en',
featureFlags: { newOnboarding: true },
},
}

How modules and packages differ

  • +
    modules: overrides for any Metro module by path fragment. Keys are matched against the Metro module name (e.g. …/node_modules/react-native-widgetkit/index.js); a key like react-native-widgetkit matches that path. Keys are tried longest-first, so subpath keys override package-level keys.
  • +
    packages: answers the native side a package asks for, keyed by the package, then its modules and views by the names its JavaScript requests. A module answers TurboModuleRegistry.get('RNCAsyncStorage'), NativeModules.RNKeychainManager and Expo’s requireNativeModule('Name'). A view answers requireNativeComponent('RNBalanceLabel'); an Expo module view, requireNativeView('MyModule', 'ProgressiveBlurView'), is MyModule_ProgressiveBlurView, and a module’s single default view is MyModule. A whole-package 'noop' answers every name the installed package asks for. Installed peach-stub-<package> packages add stubs in the same shape with no config line (Writing Custom Stubs).

If a guest bundle reads TurboModuleRegistry.get('Foo') and you have a Foo key under modules, it will not match: modules is for JS-module paths, packages is for native names.

ModuleResolution kinds

type ModuleResolution =
| 'noop' // empty module
| false // disable peach's builtin stub, use the original
| { use: string } // redirect to an existing compat stub
| { file: string } // load a project-local file
| { inline: Record<string, any> } // inline static object as module exports

Examples

Simple noop list

Silence native modules that are irrelevant in the simulator (analytics, IDFA, widgets, in-app updates):

import { defineConfig } from 'peachsim/config'
export default defineConfig({
modules: {
'@datadog/mobile-react-navigation': 'noop', // analytics, irrelevant in sim
'@shopify/react-native-performance-navigation': 'noop',
'@sparkfabrik/react-native-idfa-aaid': 'noop', // IDFA, irrelevant in browser
'react-native-widgetkit': 'noop', // iOS widgets
'sp-react-native-in-app-updates': 'noop', // in-app updates
},
})

Env only, CJS form

/** @type {import('peachsim/config').PeachConfig} */
module.exports = {
env: {
API_URL: 'http://localhost:3000',
LOG_LEVEL: 'debug',
EXPO_PUBLIC_LOG_DEBUG: 'session',
},
}

Native managers + deep inline override

Some apps read config from a JSON file deep inside their own bundle and ship several legacy NativeModules. You can override a deep file by path fragment and seam the native managers:

defineConfig({
modules: {
// mattermost patches react-native-keychain's JS entry itself; let it run
// and only provide the native manager seam below.
'react-native-keychain': false,
// override a deep file inside the bundle by path-fragment match.
'dist/assets/config.json': {
inline: {
DefaultServerUrl: 'http://localhost:8065',
DefaultServerName: 'Mattermost Demo',
AutoSelectServerUrl: true,
SentryEnabled: false,
// …
},
},
},
packages: {
'react-native-keychain': {
modules: { RNKeychainManager: './stubs/mattermost/keychain.ts' },
},
'@mattermost/rnutils': { modules: { RNUtils: './stubs/mattermost/rn-utils.ts' } },
'@mattermost/react-native-network-client': {
modules: {
GenericClient: './stubs/mattermost/network-client.ts',
ApiClient: './stubs/mattermost/network-client.ts',
WebSocketClient: './stubs/mattermost/network-client.ts',
},
},
},
})

The slots compose freely: redirect modules by path, answer each package’s native modules and views, and inline static config a package reads from its own bundle.

Env caveat: bundle-time vs runtime

Many React Native projects read env vars at bundle time via Babel plugins (react-native-dotenv, Expo’s EXPO_PUBLIC_* inliner, babel-plugin-transform-inline-environment-variables). Those values are already inlined into the bundle Metro served, so env in peach.config.ts only sets process.env.* for code that reads env at runtime.

If your code looks like process.env.API_URL after Metro and that string has been replaced by a literal in the bundle, changing env here does nothing. Rebuild the bundle with the new env (restart Metro with the new .env, or set the var in the Metro process) and reload.

How the config reaches the runtime

The CLI carries your config to the engine when it opens your app, and the engine applies the module overrides and native stubs before any guest module factory runs. Env vars that were already inlined at bundle time can’t be changed here (see the caveat above).

runtimeVersion is handled by the local host before the engine loads. Peach installs that runtime on demand and serves the app from a version-specific localhost origin. This selection applies only to that repo, so another app can follow stable or select a different version at the same time. Remove the field to follow stable again.

For a one-off module swap without writing a config file, pass it inline:

terminal
peach open <port> --replace react-native-camera=./stubs/camera.ts

peach test accepts the same --replace <module>=<file> flag, so a test run can stub a module for just that run.

Settings reference

peach.config.ts sets project defaults, and the simulator’s own controls change them while it runs. Devices and Settings lists every device setting with its default and values, and the Settings Schema covers the simulator’s own options.

Optional dev-server integration

If you want a stable /__peachsim URL on the same dev server your team already runs, install the integration that matches your stack:

The Metro plugin auto-loads peach.config.ts: withPeach embeds the full config into every bundle it serializes, so module overrides and stubs apply automatically when you drive through it. The One plugin does not read peach.config.ts; to apply module overrides to a One app, open it with the CLI (peach open <port> --project-root <app-dir>) and pass --replace for one-off swaps (see “How the config reaches the runtime” above).