PeachConfig
The main configuration object for Peach projects. Import from peachsim/config:
defineConfig is a typed pass-through; the file may also be plain CJS:
Module slots
modules
Record<string, ModuleResolution>: overrides for any Metro module by
path fragment. The key is matched against the Metro module name as a path
fragment, not a strict package name. A key like react-native-widgetkit
matches …/node_modules/react-native-widgetkit/index.js; a key like
dist/assets/config.json matches a deep file path inside a module.
Keys are sorted longest-first, so subpath keys can override package-level keys.
packages
Record<string, PackageStubs>: native stubs, keyed by the package whose
native side they answer, then by the native names its JavaScript requests.
A module answers TurboModuleRegistry, legacy NativeModules and Expo’s
requireNativeModule under its name; 'noop' is a present module whose
every method is a no-op, and a file default-exports the module object. A
view answers the name the app asks for:
| the app calls | key |
|---|---|
requireNativeComponent('RNBalanceLabel') | RNBalanceLabel |
requireNativeView('MyModule', 'ProgressiveBlurView') | MyModule_ProgressiveBlurView |
requireNativeView('MyModule') | MyModule |
'noop' renders an empty view. A view file default-exports the component.
It receives exactly the props the app passes to the native view, and may
import react, react-native, peach-kit and the packages Peach bridges
for the app. A name with no entry keeps Peach’s behavior: its built-in
implementation, else an inert module or an empty view.
An installed peach-stub-<package> package, or a library’s own
package.json, declares the same shape under a peach field with an
optional versions range; see
Publish a stub. The app’s
packages entry wins over both.
See Native View Primitives for a typed progressive-blur replacement.
Module resolution kinds
env
Record<string, string>: environment variables installed as process.env.*
inside the guest runtime.
Caveat: many React Native projects read env vars at bundle time via
Babel plugins (react-native-dotenv, Expo’s EXPO_PUBLIC_* inliner, …). Those
values are already baked into the bundle that Metro served. env here only
sets process.env.* for code that reads env at runtime; code that already
got its values inlined at bundle time will not see new values. To change
those, rebuild the bundle with the new env and reload.
settings
Partial<SettingsValues>: simulator settings overrides (device model,
appearance, network, locale, chrome). See
settings schema.
initialState
Initial app state passed to the simulator:
How the config reaches the runtime
The config travels as the ?peachConfig=<json> URL query param.
- +
applyPeachConfigToUrl(url, config)serializes into the param. - +
readPeachConfigFromSearchParams(searchParams)deserializes inside the engine. - +The engine preloads any
{ file: '…' }modules by fetching them through the/__sootsim-replacement-moduledev-server middleware (one project-local source file, whose imports are restricted toreact,react-native, and the packages the simulator bridges for this app). - +The bundle loader matches
moduleskeys against every__d()factory registration and serves the configured resolution instead.
mergePeachConfig(base, override) shallowly merges two configs by slot.