Configuration

NativeScope is configured through one root nativescope.config.ts, where you declare the modules to enable. Storage instances are still discovered automatically — you name the module, not each store. The storage block is also where its app-side behavior lives: an in-app indicator and cache invalidation for a layer like React Query.

The file

Create nativescope.config.ts at the root of your app. When Metro runs through NativeScope, the shim loads it automatically. It does not change your production bundle.

// nativescope.config.ts
import { defineNativeScopeConfig } from "react-native-nativescope/app";
 
export default defineNativeScopeConfig({
  modules: {
    storage: {
      indicator: true,
      reactQuery: true,
    },
  },
});

defineNativeScopeConfig is only there for type inference. It returns the object unchanged.

modules.storage.indicator

Shows a small badge inside your app when a change arrives from the studio. It hides itself after a moment and can be dismissed with × for the rest of the session. On Android it already sits above the navigation bar.

export default defineNativeScopeConfig({
  modules: {
    storage: {
      indicator: {
        autoHideMs: 1600,
        bottomOffset: 88,
      },
    },
  },
});

Use it when you want visual confirmation that the app received your edit. Most of the time indicator: true is all you need.

modules.storage.reactQuery

Covered in depth in the React Query bridge. The short version:

export default defineNativeScopeConfig({
  modules: {
    storage: {
      reactQuery: true,
    },
  },
});

That discovers your QueryClient and invalidates queries when the studio changes data.

Event filters

Both options accept an eventFilter that narrows which changes they react to. Every field is optional and they combine with AND.

export default defineNativeScopeConfig({
  modules: {
    storage: {
      reactQuery: {
        queryKey: ["schedule"],
        eventFilter: {
          providerId: "mmkv",
          instanceId: "cache",
        },
      },
    },
  },
});

By default the bridge only reacts to source: "studio". Changes your own app made do not trigger invalidation, because your app already knows about them.