PowerSync DevTools for Capacitor

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

Install the packages

npm install -D @powersync/diagnostics @vitejs/devtools

Add the plugin

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

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.

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:

await db.connect(connector, { diagnostics: true });

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.

iOS simulator
Android emulator

npx cap run ios --live-reload --host localhost --port 5173

In the Android emulator, localhost is the emulator, not your computer. Thus, you must first forward the dev server port to your computer:

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 shows an example.

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:

In the app, tap Unauthorized in the Vite DevTools dock.
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.
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:

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

MCP Tools

Coding agents use the Vite MCP endpoint 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.

Get Started

Configuration Details

Sync Streams

Client SDKs

Handling Writes

Maintenance & Ops

Integrations

Tools

Resources

PowerSync DevTools for Capacitor

Requirements

Set Up DevTools

MCP Tools

Troubleshooting

​Requirements

​Set Up DevTools

​MCP Tools

​Troubleshooting

Requirements

Set Up DevTools

MCP Tools

Troubleshooting