Skip to main content
The @powersync/diagnostics package adds a PowerSync panel to React Native DevTools. The panel is a plugin for Rozenite, a plugin framework for React Native DevTools, so you also install Rozenite and enable it in Metro. The plugin works with Expo and bare React Native apps.

​
Requirements

  • React Native 0.76 or later.
  • Rozenite 2.5.0 or later.
  • @powersync/diagnostics 0.1.0 or later.

​
Set Up DevTools

1

Install the packages

Add the packages to the dev dependencies in your app’s own package.json. Rozenite looks for plugins only in the packages listed there. In a monorepo, it does not find @powersync/diagnostics if only a shared package lists it.
2

Enable Rozenite in Metro

In metro.config.js, wrap your Metro configuration with withRozenite():
With enabled set from the WITH_ROZENITE environment variable, Rozenite runs only when you start Metro with WITH_ROZENITE=true.
Rozenite detects an Expo project only from an app.json file. If your Expo app uses app.config.ts or app.config.js, you must set projectType: 'expo'. Without it, React Native DevTools opens without the Rozenite tab.
3

Add the hook to your app

Call usePowerSyncDevTools() once, in a component that stays mounted while you debug, such as your root layout:
If your app creates the database later, pass null until the database exists. DevTools attaches when the hook receives the database.DevTools shows only the database that you pass to the hook. If the component unmounts, DevTools loses the connection to the database until the component mounts again.You can keep the hook in your app when you build for production. In a production build, the hook does nothing, and the DevTools code is left out of your app bundle.
4

Optional: Enable diagnostics when you connect

To show the total number of operations for each bucket in the Buckets tab, set diagnostics when you connect:
The totals require @powersync/react-native 2.4.1 or later.
5

Start the app with Rozenite

Use run:android for Android, or npx expo start if your app is already installed.
In the Android emulator, localhost is the emulator, not your computer. If the app connects to a PowerSync Service or backend on localhost, forward each port to your computer, for example adb reverse tcp:8080 tcp:8080.
6

Open PowerSync DevTools

Open React Native DevTools: press j in the Metro terminal, or select Open DevTools in the dev menu of your app. Then select the Rozenite tab, and select PowerSync in its sidebar.
React Native DevTools with the Rozenite tab and the PowerSync panel open on the Sync Status tab, next to an iPhone simulator that runs a todo list app

The PowerSync panel in React Native DevTools, next to the app on the iOS simulator.

To see what each tab shows, read Using DevTools.

​
Agent Tools

Coding agents can query the local database of your app, read its sync status, and run sync actions through the Rozenite agent CLI. To give an agent access, read Agent Tools.

​
Troubleshooting

React Native DevTools has no Rozenite tab. Check these causes:
  • Metro started without WITH_ROZENITE=true.
  • Your Expo app uses app.config.ts or app.config.js, and projectType: 'expo' is not set. If curl http://localhost:8081/json/list returns a devtoolsFrontendUrl that starts with /debugger-frontend/ instead of /rozenite/, Rozenite is not active.
Changes to metro.config.js or new plugins do not appear. Rozenite loads plugins when Metro starts. Restart Metro. Then close React Native DevTools and open it again, because an open DevTools window keeps the earlier version. The PowerSync panel shows no data. The component that calls usePowerSyncDevTools() must be mounted. The panel attaches automatically when the component mounts.