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

> Inspect the PowerSync client of a Capacitor app on an iOS simulator or Android emulator with the Vite DevTools plugin.

A Capacitor app runs in a WebView. With live reload, the WebView loads your app from the Vite dev server on your computer. Thus, the [Vite DevTools plugin](https://docs.powersync.com/tools/devtools/vite.md) can read the database of the app on the simulator or emulator.

A release build loads the app from bundled files, not from the dev server. Thus, DevTools is not available in a release build.

## Requirements

* `@powersync/capacitor` 0.10.0 or later.
* Vite 7 or later. The Vite dev server must serve your app.

## Set Up DevTools

**1. Install the packages**

```bash theme={null}
npm install -D @powersync/diagnostics @vitejs/devtools
```

**2. Add the plugin**

In `vite.config.ts`, enable Vite DevTools, add the PowerSync plugin, and configure the dev server:

```typescript theme={null}
import { defineConfig } from 'vite';
import powersyncDevtools from '@powersync/diagnostics/vite';

export default defineConfig({
  server: {
    // Lets the simulator or emulator reach the dev server during live reload.
    host: true,
    port: 5173,
    strictPort: true
  },
  devtools: { apply: 'serve' },
  plugins: [powersyncDevtools()]
});
```

The app on the simulator or emulator loads from the port that you give to `npx cap run`. By default, if that port is in use, Vite starts on the next free port, and the app cannot reach the dev server. With `strictPort: true`, Vite exits with an error instead.

The `devtools` option requires Vite 8.3 or later. If you use Vite 7, use the `DevTools()` plugin. Refer to [PowerSync DevTools for Vite](https://docs.powersync.com/tools/devtools/vite.md#set-up-devtools).

**3. Optional: Enable diagnostics when you connect**

To show the total number of operations for each bucket in the **Buckets** tab, set `diagnostics: true` when you connect:

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

**4. Run the app with live reload**

Start the dev server. Then run the app on a simulator or emulator. Use the port that you set in `server.port`.

> [tab] iOS simulator
>
> ```bash theme={null}
> npx cap run ios --live-reload --host localhost --port 5173
> ```

> [tab] Android emulator
>
> In the Android emulator, `localhost` is the emulator, not your computer. Thus, you must first forward the dev server port to your computer:
>
> ```bash theme={null}
> adb reverse tcp:5173 tcp:5173
> npx cap run android --live-reload --host localhost --port 5173
> ```
>
> If the app also connects to a PowerSync Service or backend on `localhost`, forward those ports too. The [Capacitor demo app](https://github.com/powersync-ja/powersync-js/tree/main/demos/example-capacitor) shows an example.

**5. Trust the app and open DevTools**

Vite DevTools must trust each WebView before it shows data. To trust the app on the simulator or emulator:

1. In the app, tap **Unauthorized** in the Vite DevTools dock.
2. Find the six-digit code in the dev server terminal. Below the code, the terminal shows the user agent of the client that asked for it, for example `iOS 18.7 mobile`.
3. Type the code in the app.

Then tap the **PowerSync** entry in the dock.

You can also use DevTools in a browser on your computer. The browser shows the same data as the dock in the app:

1. Open the link that the dev server terminal shows next to the code. The link opens in your default browser and trusts that browser. You cannot use the link to trust the app, because the link does not open in the app.
2. In that browser, open `http://localhost:5173/__devtools/`. The app on the simulator or emulator is attached as a database. If more than one database is attached, select one in the database list in the DevTools header.

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

## MCP Tools

Coding agents use the [Vite MCP endpoint](https://docs.powersync.com/tools/devtools/mcp.md) to read the database of the app on the simulator or emulator. Keep the app open with live reload while the agent uses the tools.

## Troubleshooting

**DevTools shows "No PowerSync database attached".** Sometimes the database of the app detaches from DevTools and does not attach again. To attach it again, close the app and open it again.

**Requests to your backend fail during live reload.** With live reload, the app loads from `http://localhost:5173`, not from the device. If your backend allows only specific origins (CORS), add this address. Or send the requests through the dev server with [`server.proxy`](https://vite.dev/config/server-options#server-proxy).


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