> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powersync.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PowerSync DevTools for React Native

> Inspect the PowerSync client of a React Native or Expo app in React Native DevTools, with the PowerSync Rozenite plugin.

The `@powersync/diagnostics` package adds a **PowerSync** panel to [React Native DevTools](https://reactnative.dev/docs/react-native-devtools). The panel is a plugin for [Rozenite](https://www.rozenite.dev/), 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**

```bash theme={null}
npm install -D @powersync/diagnostics @rozenite/metro @rozenite/plugin-bridge @rozenite/agent-bridge
```

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()`:

> [tab] Expo
>
> ```javascript theme={null}
> const { getDefaultConfig } = require('expo/metro-config');
> const { withRozenite } = require('@rozenite/metro');
>
> module.exports = withRozenite(getDefaultConfig(__dirname), {
>   enabled: process.env.WITH_ROZENITE === 'true',
>   projectType: 'expo'
> });
> ```

> [tab] Bare React Native
>
> ```javascript theme={null}
> const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
> const { withRozenite } = require('@rozenite/metro');
>
> const config = {};
>
> module.exports = withRozenite(mergeConfig(getDefaultConfig(__dirname), config), {
>   enabled: process.env.WITH_ROZENITE === 'true'
> });
> ```

With `enabled` set from the `WITH_ROZENITE` environment variable, Rozenite runs only when you start Metro with `WITH_ROZENITE=true`.

> [!WARNING]
>
> 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:

```tsx theme={null}
import { usePowerSyncDevTools } from '@powersync/diagnostics/react-native';

export default function RootLayout() {
  // `db` is your PowerSyncDatabase instance.
  usePowerSyncDevTools(db);
  // ...
}
```

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:

```typescript theme={null}
await db.connect(connector, { diagnostics: __DEV__ });
```

The totals require `@powersync/react-native` 2.4.1 or later.

**5. Start the app with Rozenite**

> [tab] Expo
>
> ```bash theme={null}
> WITH_ROZENITE=true npx expo run:ios
> ```
>
> Use `run:android` for Android, or `npx expo start` if your app is already installed.

> [tab] Bare React Native
>
> ```bash theme={null}
> WITH_ROZENITE=true npx react-native start
> ```
>
> Then run the app with `npx react-native run-ios` or `npx react-native run-android`.

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](https://mintcdn.com/powersync/vuaBIz1M9QJDrWLB/images/tools/devtools-react-native.png?fit=max\&auto=format\&n=vuaBIz1M9QJDrWLB\&q=85\&s=a5422ac47bf8d7f11247a74371e110f3)

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

To see what each tab shows, read [Using DevTools](https://docs.powersync.com/tools/devtools/using-devtools.md).

## 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](https://docs.powersync.com/tools/devtools/agent-tools.md#react-native).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.