Quickstart

Install

Add it as a development dependency. It must never be a runtime dependency.

npm install --save-dev react-native-nativescope

yarn add --dev react-native-nativescope

pnpm add -D react-native-nativescope

bun add --dev react-native-nativescope

Run

Start your project through NativeScope instead of starting Metro directly.

npx nativescope

yarn nativescope

pnpm nativescope

bunx nativescope

That single command does four things:

1. Inspects your package.json and reports which storage libraries it found.
2. Starts Metro with the NativeScope resolver attached.
3. Sets up an adb reverse tunnel if an Android device is connected, and keeps it alive if the cable drops or the adb server restarts.
4. Opens the studio in your browser at http://127.0.0.1:4782.

To attach the resolver, NativeScope creates metro.config.js when the project has none. If a JavaScript Metro config already exists, it is preserved as metro.config.original.js and a small delegate is generated in its place. This wrapper is safe to keep: release builds resolve the real storage modules directly. The generated file also includes exact rollback instructions.

Now launch your app the way you normally would. The moment it connects, its storages appear in the sidebar.

At this point, discovery, inspection and writes in both directions are working. No app file is required for that core workflow.

Keep cached screens in sync (optional)

NativeScope writes the real storage value immediately, but if your screen renders that value through React Query, the cache can keep showing the old one until something invalidates it. A small, optional config file closes that gap — see the React Query bridge. Neither it nor the in-app indicator is needed for storage discovery.

Verify it worked

The startup output tells you what was detected before anything else happens:

NativeScope

Project: my-app
Detected in package.json:
  ✓ AsyncStorage
  ✓ MMKV

This startup list is an informational dependency check. Runtime discovery follows the modules your app actually imports and the MMKV instances or SQLite databases it opens. If a direct dependency you expected is missing here, check the target project's package.json and the --project path.

Already running Metro?

If you manage Metro yourself, run nativescope --no-metro and attach the wrapper to your own Metro config. Devices & connection covers that setup, when to choose it, and how it compares to letting NativeScope start Metro for you.

Common adjustments

Use a different port:

npx nativescope --port 5000

yarn nativescope --port 5000

pnpm nativescope --port 5000

bunx nativescope --port 5000

Run against a project in another directory:

npx nativescope --project ../other-app

yarn nativescope --project ../other-app

pnpm nativescope --project ../other-app

bunx nativescope --project ../other-app

Do not open the browser automatically:

npx nativescope --no-open

yarn nativescope --no-open

pnpm nativescope --no-open

bunx nativescope --no-open

The full list is in the CLI reference.

Next

Read the React Query bridge for automatic discovery, custom QueryClient setup and precise invalidation filters.