Configuration

sootsim.config.ts

Create a config file in your project root:

terminal

sootsim config init

Full config reference

import { defineConfig } from 'sootsim/config'
export default defineConfig({
// module resolution overrides
modules: {
// stub a package as empty (no-op)
'react-native-analytics': 'noop',
// disable builtin stub, use original package
'react-native-gesture-handler': false,
// redirect to an existing compat stub
'my-native-lib': { use: 'expo-haptics' },
// use a custom file
'my-native-camera': { file: './stubs/camera.ts' },
// inline stub
'react-native-config': {
inline: {
API_URL: 'http://localhost:3000',
ENV: 'development',
},
},
},
// environment variables (injected as process.env.*)
env: {
API_URL: 'http://localhost:3000',
DEBUG: 'true',
},
// simulator settings
settings: {
deviceModel: 'iphone-16-pro',
colorScheme: 'dark',
showFrame: true,
showTouches: false,
networkCondition: 'wifi',
language: 'en',
region: 'US',
},
// initial app state
initialState: {
authenticated: false,
locale: 'en',
colorScheme: 'light',
featureFlags: {
newOnboarding: true,
},
},
})

Settings

All settings can be configured via:

  1. sootsim.config.ts — project-level defaults
  2. CLI flags — per-invocation overrides
  3. simulator UI — runtime changes (notification center pull-down)

Device settings

settingCLI flagvaluesdefault
deviceModel--deviceiphone-se, iphone-15, …, iphone-16-pro-maxiphone-15-pro
orientation--orientationportrait, landscapeportrait

Appearance settings

settingCLI flagvaluesdefault
colorScheme--themelight, dark, autolight
reduceMotionbooleanfalse
boldTextbooleanfalse
fontSize0.5-2.01.0

Network settings

settingCLI flagvaluesdefault
networkCondition--networkwifi, lte, fast-3g, slow-3g, offlinewifi

Locale settings

settingCLI flagvaluesdefault
language--languageISO 639-1 codesen
region--regionISO 3166-1 codesUS

Simulator settings

settingCLI flagvaluesdefault
showFrame--framebooleantrue
showTouchesbooleanfalse
showStatusBarbooleantrue
showHomeIndicatorbooleantrue
a11yModeoff, default, alwaysdefault
inspectModebooleanfalse

Optional dev-server integration

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

These integrations do not replace sootsim.config.ts. They simply expose SootSim on the existing dev server. You can still skip them entirely and use sootsim open <port> against a running app.