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:
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
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 likereact-native-widgetkitmatches 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 itsmodulesandviewsby the names its JavaScript requests. A module answersTurboModuleRegistry.get('RNCAsyncStorage'),NativeModules.RNKeychainManagerand Expo’srequireNativeModule('Name'). A view answersrequireNativeComponent('RNBalanceLabel'); an Expo module view,requireNativeView('MyModule', 'ProgressiveBlurView'), isMyModule_ProgressiveBlurView, and a module’s single default view isMyModule. A whole-package'noop'answers every name the installed package asks for. Installedpeach-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
Examples
Simple noop list
Silence native modules that are irrelevant in the simulator (analytics, IDFA, widgets, in-app updates):
Env only, CJS form
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:
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:
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:
- +Metro Plugin for Expo, bare React Native, and any Metro app
- +One Plugin for One apps
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).