Wrapping an existing app

SootSim works with existing React Native apps without app code changes. Start the app the way you already do, then either connect to its dev server with sootsim open or add the optional /__soot integration.

Basic usage

Start your app normally:

# expo
npx expo start

# bare react-native / metro
npx react-native start

# one
bun dev

Then connect SootSim to the running dev server:

sootsim open 8081

If you omit the port, sootsim open scans for likely React Native dev servers and lets you pick one.

Optional /__soot integration

If you want SootSim available on the same dev server your team already runs, install the optional integration:

sootsim setup-repo

That adds:

• withSootsim() for Metro / Expo / bare React Native projects
• sootsimPlugin() for One apps

The integration is optional. It just exposes a stable /__soot URL on the existing dev server; it does not create a separate app target.

Checking compatibility

Before you wire a project into SootSim, scan its dependencies:

sootsim compat

The scan reports:

• Full support — the common runtime surface works
• Partial support — major APIs work, but some behavior is still missing
• Auto-stub — the package resolves, but only through a basic fallback
• Unsupported — the package still depends on native SDK behavior

Handling unsupported packages

Option 1: noop stub

For packages you do not need in the simulator:

import { defineConfig } from 'sootsim/config'

export default defineConfig({
  modules: {
    'react-native-analytics': 'noop',
  },
})

Option 2: custom stub

For packages that need real behavior:

// stubs/my-camera.ts
export function takePicture() {
  return { uri: 'https://placekitten.com/400/400' }
}

import { defineConfig } from 'sootsim/config'

export default defineConfig({
  modules: {
    'react-native-camera': { file: './stubs/my-camera.ts' },
  },
})

Option 3: inline stub

For simple key-value packages:

import { defineConfig } from 'sootsim/config'

export default defineConfig({
  modules: {
    'react-native-config': {
      inline: { API_URL: 'http://localhost:3000' },
    },
  },
})

Related

• Metro Plugin
• One Plugin
• Writing custom stubs