diff --git a/.github/vale/config/vocabularies/PowerSync/accept.txt b/.github/vale/config/vocabularies/PowerSync/accept.txt index 991997fce..2a534ce0d 100644 --- a/.github/vale/config/vocabularies/PowerSync/accept.txt +++ b/.github/vale/config/vocabularies/PowerSync/accept.txt @@ -329,3 +329,5 @@ PWAs XCFramework growable ps_crud +loopback +oplog diff --git a/client-sdks/frameworks/nuxt.mdx b/client-sdks/frameworks/nuxt.mdx index 88fc564f1..17ce06336 100644 --- a/client-sdks/frameworks/nuxt.mdx +++ b/client-sdks/frameworks/nuxt.mdx @@ -63,10 +63,6 @@ export default defineNuxtConfig({ }); ``` - - If you are using Tailwind CSS in your project, see [Known Issues](/tools/nuxt-inspector#known-issues) on the Nuxt Inspector page. - - ## Configure PowerSync in Your Project ### Define your Schema @@ -164,13 +160,14 @@ export class PowerSyncConnector implements PowerSyncBackendConnector { Create a [Nuxt plugin](https://nuxt.com/docs/guide/directory-structure/plugins) at `plugins/powersync.client.ts`. The `.client.ts` suffix ensures this only runs in the browser. ```typescript plugins/powersync.client.ts -import { NuxtPowerSyncDatabase, createPowerSyncPlugin } from '@powersync/nuxt'; +import { PowerSyncDatabase } from '@powersync/web'; +import { createPowerSyncPlugin } from '@powersync/nuxt'; import { AppSchema } from '~/powersync/AppSchema'; import { PowerSyncConnector } from '~/powersync/PowerSyncConnector'; export default defineNuxtPlugin({ async setup(nuxtApp) { - const db = new NuxtPowerSyncDatabase({ + const db = new PowerSyncDatabase({ database: { dbFilename: 'my-app.sqlite' }, @@ -285,4 +282,4 @@ const lists = await db.selectFrom('lists').selectAll().execute(); ## DevTools -The `@powersync/nuxt` module includes a PowerSync diagnostics panel that integrates with Nuxt DevTools. It shows sync status, local data, config, and logs. See [Nuxt DevTools Integration](/tools/nuxt-inspector) for setup instructions and available views. +The `@powersync/nuxt` module adds PowerSync DevTools to Nuxt DevTools. It shows the sync status, buckets, Sync Streams, local data, the schema, and logs. Read [PowerSync DevTools for Nuxt](/tools/devtools/nuxt) to set it up. diff --git a/docs.json b/docs.json index 35fcf5a0b..38d71c33a 100644 --- a/docs.json +++ b/docs.json @@ -332,7 +332,8 @@ "client-sdks/reference/flutter", "client-sdks/frameworks/flutter-web-support", "client-sdks/orms/flutter-orm-support", - "client-sdks/reference/flutter-api" + "client-sdks/reference/flutter-api", + "tools/dart-devtools-extension" ] }, { @@ -526,17 +527,25 @@ "tools/cli", "tools/powersync-dashboard", "tools/diagnostics-client", - "tools/local-development", - "tools/terraform", - "tools/ai-tools", { "group": "DevTools", "pages": [ "tools/devtools-overview", - "tools/dart-devtools-extension", - "tools/nuxt-inspector" + { + "group": "Set Up", + "pages": [ + "tools/devtools/vite", + "tools/devtools/nuxt", + "tools/devtools/node" + ] + }, + "tools/devtools/using-devtools", + "tools/devtools/mcp" ] - } + }, + "tools/local-development", + "tools/terraform", + "tools/ai-tools" ] }, { @@ -588,6 +597,10 @@ } }, "redirects": [ + { + "source": "/tools/nuxt-inspector", + "destination": "/tools/devtools/nuxt" + }, { "source": "/overview-1", "destination": "/intro/powersync-overview" diff --git a/images/nuxt/inspector.png b/images/nuxt/inspector.png deleted file mode 100644 index 2f8301c35..000000000 Binary files a/images/nuxt/inspector.png and /dev/null differ diff --git a/images/tools/devtools-buckets.png b/images/tools/devtools-buckets.png new file mode 100644 index 000000000..7080a9ba2 Binary files /dev/null and b/images/tools/devtools-buckets.png differ diff --git a/images/tools/devtools-config.png b/images/tools/devtools-config.png new file mode 100644 index 000000000..665146f59 Binary files /dev/null and b/images/tools/devtools-config.png differ diff --git a/images/tools/devtools-data-inspector.png b/images/tools/devtools-data-inspector.png new file mode 100644 index 000000000..0ee7314de Binary files /dev/null and b/images/tools/devtools-data-inspector.png differ diff --git a/images/tools/devtools-header-highlighted.png b/images/tools/devtools-header-highlighted.png new file mode 100644 index 000000000..c98defa2a Binary files /dev/null and b/images/tools/devtools-header-highlighted.png differ diff --git a/images/tools/devtools-header.png b/images/tools/devtools-header.png new file mode 100644 index 000000000..58e6f6bce Binary files /dev/null and b/images/tools/devtools-header.png differ diff --git a/images/tools/devtools-logs.png b/images/tools/devtools-logs.png new file mode 100644 index 000000000..4bd286b78 Binary files /dev/null and b/images/tools/devtools-logs.png differ diff --git a/images/tools/devtools-multiple-tabs.png b/images/tools/devtools-multiple-tabs.png new file mode 100644 index 000000000..1a6ef0b45 Binary files /dev/null and b/images/tools/devtools-multiple-tabs.png differ diff --git a/images/tools/devtools-nuxt.png b/images/tools/devtools-nuxt.png new file mode 100644 index 000000000..c34fb727b Binary files /dev/null and b/images/tools/devtools-nuxt.png differ diff --git a/images/tools/devtools-streams.png b/images/tools/devtools-streams.png new file mode 100644 index 000000000..780cda446 Binary files /dev/null and b/images/tools/devtools-streams.png differ diff --git a/images/tools/devtools-sync-status.png b/images/tools/devtools-sync-status.png new file mode 100644 index 000000000..391c40070 Binary files /dev/null and b/images/tools/devtools-sync-status.png differ diff --git a/images/tools/devtools-vite-dock.png b/images/tools/devtools-vite-dock.png new file mode 100644 index 000000000..6893a287c Binary files /dev/null and b/images/tools/devtools-vite-dock.png differ diff --git a/tools/ai-tools.mdx b/tools/ai-tools.mdx index ab5b51f5a..613dc2211 100644 --- a/tools/ai-tools.mdx +++ b/tools/ai-tools.mdx @@ -63,6 +63,10 @@ npx add-mcp https://docs.powersync.com/mcp Or add the URL manually in your AI tool's MCP settings. You can also use the contextual menu on any docs page for quick access — it includes options to copy the server URL or connect directly to Cursor or VS Code. + + To give an agent access to your running app's PowerSync client, use the [PowerSync DevTools MCP tools](/tools/devtools/mcp). + + ### Full Documentation Text For broad context about PowerSync, we provide two plain-text versions of the full documentation: diff --git a/tools/devtools-overview.mdx b/tools/devtools-overview.mdx index 5b679b74e..695a24a30 100644 --- a/tools/devtools-overview.mdx +++ b/tools/devtools-overview.mdx @@ -1,36 +1,83 @@ --- -title: "DevTools Integrations" -description: "IDE and framework DevTools integrations for inspecting PowerSync client-side databases and sync state during development." +title: "PowerSync DevTools" +description: "Inspect the live state of your app's PowerSync client during development, in your browser DevTools or through MCP tools for coding agents." sidebarTitle: "Overview" --- -PowerSync currently provides DevTools integrations for Dart/Flutter and Nuxt. These embed a diagnostics panel into your existing IDE or framework tooling, so you can inspect your app's local database, Sync Stream state, and JWT credentials without launching a separate tool. They are available in development builds only. - - Support for additional frameworks is under consideration. If you'd like to see a specific integration, submit an idea or vote for it on the [PowerSync Roadmap](https://roadmap.powersync.com). + PowerSync DevTools is currently available for [Vite](/tools/devtools/vite), [Nuxt](/tools/devtools/nuxt), and [Node.js](/tools/devtools/node) apps. - - - Inspect databases, run SQL queries, and view Sync Stream state inside Dart & Flutter DevTools. +Use PowerSync DevTools to: + +- Check that the client is connected and up to date, and see sync errors. +- Look at the data on the device, and run SQL on it. +- See which buckets and Sync Streams the client syncs, and how far each one has downloaded. +- See the local changes that wait to upload. +- Inspect the client configuration, such as the endpoint, user ID, connection parameters, and schema. +- Read the SDK logs. +- Test offline behavior: disconnect, reconnect, or clear and re-sync. + +Coding agents can query the same client and run sync actions through [MCP tools](/tools/devtools/mcp) when you use Vite, Nuxt DevTools 4, or Node.js. + +DevTools runs in development only and adds nothing to a production build. + + + ![PowerSync DevTools panel showing the Sync Status tab](/images/tools/devtools-vite-dock.png) + + +## How It Works + +Your Vite or Nuxt dev server serves DevTools. In a Node.js app, your app process serves it instead. + +```mermaid +flowchart LR + App["Your app
(browser tab or Node process)"] -- "live database" --> Host["Dev server
(Vite, Nuxt, or your Node app)"] + Host --> UI["DevTools window"] + Host --> Agent["Coding agent
(MCP)"] +``` + +DevTools reads from the database that your app has open, so it shows the same data that your app sees. + +## Set Up DevTools + + + + React, Vue, Svelte, or any web app that uses Vite 7 or later. - - Inspect sync status, local data, config, and logs inside Nuxt DevTools. + + Nuxt apps that use `@powersync/nuxt` with Nuxt DevTools 3 or 4. + + + + Node.js apps that use `@powersync/node`. -## DevTools vs. Sync Diagnostics Client + + Support for more platforms is under consideration. To ask for a specific integration, submit an idea or vote for it on the [PowerSync Roadmap](https://roadmap.powersync.com). + -The DevTools integrations and the [Sync Diagnostics Client](/tools/diagnostics-client) serve different purposes and complement each other. +## Usage and MCP Tools -The DevTools integrations connect to your app's running process and show you what is happening on the client — local SQLite data, sync state, and any issues within the app itself. + + + What each tab is for and which actions you can run. + + + + Give a coding agent access to your app's live PowerSync client. + + + +## DevTools vs. Sync Diagnostics Client -The Sync Diagnostics Client connects via a user JWT and PowerSync endpoint. It shows sync-level data — table, row, operation and bucket counts, and stream subscriptions — as seen through the sync connection. +Use DevTools to inspect the client in your running app. Use the [Sync Diagnostics Client](/tools/diagnostics-client) to see the data that the Service syncs to a specific user. You can use both in tandem. -| | DevTools integrations | Sync Diagnostics Client | +| | PowerSync DevTools | Sync Diagnostics Client | | --- | --- | --- | -| **How it connects** | Directly to your app's running process | Via a user JWT + PowerSync endpoint | -| **What you inspect** | Local SQLite data and sync state within the app | Sync-level data: buckets, operations, stream subscriptions | +| **How it connects** | To your running app | With a user JWT and the PowerSync endpoint | +| **What you inspect** | Local SQLite data and sync state in your app | Sync data: buckets, operations, stream subscriptions | | **Environment** | Development only | Any environment | -| **SDK-specific** | Yes (Dart/Flutter, Nuxt) | No — works with all SDKs | +| **SDK-specific** | Yes | No. It works with all SDKs. | diff --git a/tools/devtools/mcp.mdx b/tools/devtools/mcp.mdx new file mode 100644 index 000000000..b735de032 --- /dev/null +++ b/tools/devtools/mcp.mdx @@ -0,0 +1,129 @@ +--- +title: "PowerSync DevTools MCP Tools" +description: "Give a coding agent access to your app's live PowerSync client through the PowerSync DevTools MCP endpoint." +sidebarTitle: "MCP Tools" +--- + +PowerSync DevTools exposes MCP (Model Context Protocol) tools that let a coding agent, such as Claude Code or Codex, query your app's local database, read its sync status, and run sync actions, such as reconnect or clear the local data. + + + These tools work with your running app. To let an agent search the PowerSync documentation, use the [docs MCP server](/tools/ai-tools#mcp-server) instead. + + +## Endpoints + +| Host | Endpoint | +| --- | --- | +| Vite | `http://localhost:5173/__devtools/__mcp` (use your dev server port) | +| Nuxt DevTools 4 | `http://localhost:3000/__devtools/__mcp` (use your dev server port) | +| Node.js | `/__mcp`, where `url` is the value that `enablePowerSyncDiagnostics()` returns | + +Nuxt DevTools 3 does not have an MCP endpoint. + +On the web, the tools get the database from an open app tab. Keep your app open in a browser that Vite DevTools trusts, or the tools return an error. + +For a Node.js app, set a fixed `port` in `enablePowerSyncDiagnostics()` so that the endpoint stays the same when your app restarts. + +## Connect a Coding Agent + +The endpoint accepts only requests that have a loopback `Origin` header, such as `http://localhost:5173`. Some MCP clients do not send this header, so add it to the client configuration. + +For example, to add the Vite endpoint to Claude Code: + +```bash +claude mcp add --transport http powersync-devtools http://localhost:5173/__devtools/__mcp --header "Origin: http://localhost:5173" +``` + +If your MCP client cannot send the header, set `allowedOrigins: false`. Read [Origin and Authorization](#origin-and-authorization). + + + Coding agents such as Claude Code can add the server themselves. Start your dev server, open your app, and give the agent a prompt like this one: + + ```text + Connect to the PowerSync DevTools MCP server of my running app. + The endpoint is http://localhost:5173/__devtools/__mcp. It uses the Streamable HTTP transport. + Every request must send the header "Origin: http://localhost:5173". + Add the server, then call powersync_sources and powersync_status and tell me the sync state. + ``` + + Change the URL and the port to match your host. Some agents must restart before they can use a new MCP server. + + +## Tools + +The tools take positional arguments named `arg0` and `arg1`. The last argument of most tools is the database ID. Pass `null` to use the first attached database, or call `powersync_sources` to list the IDs. + +| Tool | Arguments | Returns | +| --- | --- | --- | +| `powersync_sources` | None | The attached databases, with their ID and SDK. | +| `powersync_query` | `arg0`: `{ sql, params? }`
`arg1`: database ID or `null` | `{ columns, rows }`. Each row is an array in column order. | +| `powersync_schema` | `arg0`: database ID or `null` | The schema, as the PowerSync SQLite core receives it. | +| `powersync_info` | `arg0`: database ID or `null` | The endpoint, the token, the client ID, the connection method, and the core version. | +| `powersync_status` | `arg0`: database ID or `null` | The last sync status that the client reported. | +| `powersync_upload-queue` | `arg0`: database ID or `null` | The number and size of the local changes that wait to upload. | +| `powersync_action` | `arg0`: `{ action, args? }`
`arg1`: database ID or `null` | Runs one of these actions: `reconnect`, `disconnect`, `clearData`, `requestCheckpoint`, `subscribeStream`, `unsubscribeStream`. | + +For `subscribeStream` and `unsubscribeStream`, `args` is `{ name, params?, ttl?, priority? }`. + + + `powersync_query` can change data. `powersync_action` with `clearData` deletes the local data, including the local changes in the upload queue, and downloads the data again. `powersync_info` returns the current JWT. Give these tools only to agents that you trust. + + +## Origin and Authorization + +To change how the endpoint checks requests, use the `mcp` setting: + +| Value | Result | +| --- | --- | +| `'auto'` | The default. The endpoint accepts requests with a loopback `Origin` header. | +| `{ allowedOrigins: false }` | The endpoint also accepts requests without an `Origin` header. Use this only when the server listens on `localhost`. | +| `{ authorization: '' }` | Requests must also send `Authorization: Bearer `. Read the token from an environment variable. | +| `false` | Turns off the endpoint. | + +Set it in your host: + + + + ```typescript + export default defineConfig({ + devtools: { apply: 'serve', mcp: { allowedOrigins: false } }, + plugins: [powersyncDevtools()] + }); + ``` + + + ```typescript + export default defineConfig({ + plugins: [...(await DevTools({ mcp: { allowedOrigins: false } })), powersyncDevtools()] + }); + ``` + + + ```typescript + export default defineNuxtConfig({ + vite: { + devtools: { mcp: { allowedOrigins: false } } + } + }); + ``` + + + ```typescript + const devtools = await enablePowerSyncDiagnostics(db, { mcp: { allowedOrigins: false } }); + ``` + + + +## Test the Endpoint + +Use `curl` to check that the endpoint works. This example counts the operations in the local oplog: + +```bash +curl -X POST http://localhost:5173/__devtools/__mcp \ + -H 'Origin: http://localhost:5173' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"powersync_query","arguments":{"arg0":{"sql":"SELECT count(*) AS operations FROM ps_oplog"},"arg1":null}}}' +``` + +If the response is `403 Forbidden`, the request has no loopback `Origin` header. diff --git a/tools/devtools/node.mdx b/tools/devtools/node.mdx new file mode 100644 index 000000000..e2f4e2b2e --- /dev/null +++ b/tools/devtools/node.mdx @@ -0,0 +1,75 @@ +--- +title: "PowerSync DevTools for Node.js" +description: "Serve PowerSync DevTools from your Node.js app process and open it in a browser." +sidebarTitle: "Node.js" +--- + +A Node.js app has no dev server, so your app process serves DevTools and you open it in a browser. + +## Requirements + +- `@powersync/node` 1.2.0 or later. +- Node.js 20.16 or later. + +## Set Up DevTools + + + + ```bash + npm install -D @powersync/diagnostics + ``` + + + After you create the database, call `enablePowerSyncDiagnostics()` in development only. + + ```typescript + import { PowerSyncDatabase } from '@powersync/node'; + + const db = new PowerSyncDatabase({ schema: AppSchema, database: { dbFilename: 'app.db' } }); + await db.connect(connector, { diagnostics: true }); + + if (process.env.NODE_ENV !== 'production') { + const { enablePowerSyncDiagnostics } = await import('@powersync/diagnostics/node'); + const devtools = await enablePowerSyncDiagnostics(db); + console.log(`PowerSync DevTools: ${devtools.signInUrl}`); + } + ``` + + Import `@powersync/diagnostics` inside the check. A production install without dev dependencies (`npm ci --omit=dev`) does not include the package. A static import at the top of the file then stops your app at startup. + + `diagnostics: true` is optional. Without it, the **Buckets** tab does not show the total number of operations for each bucket. + + + Start your app and open the link that it prints. The link contains a one-time code that is valid for five minutes and for one browser. If the code expires, open `devtools.url` to print a new link in the terminal. + + + +To see what each tab is for, read [Using DevTools](/tools/devtools/using-devtools). To connect a coding agent to the MCP endpoint at `/__mcp`, read [MCP Tools](/tools/devtools/mcp). + +## Options + +Pass options as the second argument: `enablePowerSyncDiagnostics(db, { port: 4000 })`. + +| Option | Default | Description | +| --- | --- | --- | +| `port` | A random free port | The port that DevTools listens on. A random port makes DevTools harder for other websites to find. | +| `host` | `localhost` | The host that the server binds to. | +| `auth` | `true` | If `true`, the browser must sign in with a one-time code. If `false`, any browser on your machine can open DevTools. | +| `open` | `false` | If `true`, DevTools opens in your browser when the server starts. | +| `sdk` | `@powersync/node` | The SDK label that the UI shows. | +| `id` | `node-1` | The database ID that the UI and the MCP tools show. | +| `mcp` | `'auto'` | The MCP endpoint setting. See [MCP Tools](/tools/devtools/mcp#origin-and-authorization). | + + + If you set `host` to an address other than `localhost`, other devices on your network can reach DevTools, which can read and change your local data. In that case, keep `auth` set to `true`. + + +## Return Value + +`enablePowerSyncDiagnostics()` returns an object with these properties: + +| Property | Description | +| --- | --- | +| `url` | The address of DevTools, such as `http://localhost:51234`. | +| `signInUrl` | The link to open. It contains the one-time code. If `auth` is `false`, it is the same as `url`. | +| `close()` | Stops the server and detaches the database. | diff --git a/tools/devtools/nuxt.mdx b/tools/devtools/nuxt.mdx new file mode 100644 index 000000000..8fbb3efb3 --- /dev/null +++ b/tools/devtools/nuxt.mdx @@ -0,0 +1,138 @@ +--- +title: "PowerSync DevTools for Nuxt" +description: "Show PowerSync DevTools in Nuxt DevTools with the @powersync/nuxt module." +sidebarTitle: "Nuxt" +--- + +The `@powersync/nuxt` module includes PowerSync DevTools and adds it to [Nuxt DevTools](https://devtools.nuxt.com), so you do not need to install another package. + +## Requirements + +- `@powersync/nuxt` 2.0.0 or later. +- Nuxt DevTools 3 or 4. + +If you are upgrading from `@powersync/nuxt` 1.x or earlier, follow the [Migration Guide](#migration-guide) first. + +## Set Up DevTools + + + + Set `useDiagnostics: true` in `nuxt.config.ts`. + + ```typescript + export default defineNuxtConfig({ + modules: ['@powersync/nuxt'], + powersync: { + useDiagnostics: true + }, + vite: { + optimizeDeps: { + exclude: ['@powersync/web'] + }, + worker: { + format: 'es' + } + } + }); + ``` + + The module applies this option only during `nuxt dev`, so DevTools is not added to a production build. + + + To show the total number of operations for each bucket in the **Buckets** tab, pass `diagnostics: true` when you connect in your PowerSync plugin. + + ```typescript + await db.connect(connector, { diagnostics: true }); + ``` + + + Start `nuxt dev` and open Nuxt DevTools. The module detects your Nuxt DevTools version, and the remaining steps depend on it. + + + + Nuxt 4 installs Nuxt DevTools 3 by default. + + Select the **PowerSync** tab in Nuxt DevTools. You can also open DevTools directly at `http://localhost:3000/__powersync/`. Your app's route middleware, such as an auth guard, does not apply to this page. + + + The MCP tools need Nuxt DevTools 4. + + + + Nuxt DevTools 4 is in beta. It runs on Vite DevTools and needs Nuxt 4.5 or later. + + Because Nuxt 4 depends on Nuxt DevTools 3, you must install version 4 and override the version that Nuxt uses. For example, with pnpm, add this to `pnpm-workspace.yaml`: + + ```yaml + overrides: + '@nuxt/devtools': 4.0.0-beta.2 + ``` + + {/* TODO: Update the version when Nuxt DevTools 4 is stable. */} + + Then open DevTools: + + 1. The first time, DevTools asks you to trust the browser. Enter the six-digit code from the terminal in the browser, or open the link that the terminal prints. + 2. Click the **PowerSync** entry in the DevTools dock. + + With Nuxt DevTools 4, coding agents can use the [MCP tools](/tools/devtools/mcp) at `http://localhost:3000/__devtools/__mcp`. + + + + + + + ![PowerSync DevTools in the Nuxt DevTools PowerSync tab](/images/tools/devtools-nuxt.png) + + +To see what each tab shows, read [Using DevTools](/tools/devtools/using-devtools). + +## Troubleshooting + +**Nuxt DevTools 4 shows "No PowerSync database attached" after the app tab was idle.** Reload the app tab to attach the database again. + +## Migration Guide + +`@powersync/nuxt` 2.0.0 replaces the PowerSync inspector with PowerSync DevTools. The `useDiagnostics` option keeps its name and now turns on DevTools, so you do not need to change it. To upgrade from 1.x or earlier, follow these steps. + + + + `NuxtPowerSyncDatabase` is removed. Use `PowerSyncDatabase` from `@powersync/web`, and pass `diagnostics: true` when you connect. + + ```diff + - import { NuxtPowerSyncDatabase } from '@powersync/nuxt'; + + import { PowerSyncDatabase } from '@powersync/web'; + + - const db = new NuxtPowerSyncDatabase({ database: { dbFilename: 'app.sqlite' }, schema: AppSchema }); + + const db = new PowerSyncDatabase({ database: { dbFilename: 'app.sqlite' }, schema: AppSchema }); + + - await db.connect(connector); + + await db.connect(connector, { diagnostics: true }); + ``` + + `NuxtPowerSyncDatabase` set `enableMultiTabs: true` on every browser, but `PowerSyncDatabase` turns off multi-tab support on Safari, iOS, and Android by default. To keep the old behavior, set `enableMultiTabs: true` in the `database` options. + + + These exports are removed: + + - `usePowerSyncInspector` + - `usePowerSyncInspectorDiagnostics` + - The types `UsePowerSyncInspectorDiagnosticsReturn` and `UsePowerSyncInspectorDiagnosticsTotals` + + If you added `diagnosticsSchema` to your schema, remove it. DevTools no longer adds tables to your database. + + + The module no longer uses UnoCSS. If you added this setting to avoid a conflict with Tailwind CSS, remove it: + + ```diff + export default defineNuxtConfig({ + - unocss: { + - autoImport: false + - } + }); + ``` + + + The `/__powersync-inspector` page is removed. Use the **PowerSync** tab in Nuxt DevTools. With Nuxt DevTools 3, you can also open `/__powersync/`. + + diff --git a/tools/devtools/using-devtools.mdx b/tools/devtools/using-devtools.mdx new file mode 100644 index 000000000..6a8fbc500 --- /dev/null +++ b/tools/devtools/using-devtools.mdx @@ -0,0 +1,91 @@ +--- +title: "Using PowerSync DevTools" +description: "What each PowerSync DevTools tab shows, and the sync actions you can run from DevTools." +sidebarTitle: "Using DevTools" +--- + +PowerSync DevTools has the same tabs in Vite, Nuxt, and Node.js. To set it up, start with the [overview](/tools/devtools-overview). + +## Header and Status Bar + + + ![DevTools header with three numbered controls: 1 the database list, 2 Sync now, 3 Clear and re-sync. The status bar is below the header.](/images/tools/devtools-header-highlighted.png) + + +The status bar stays visible on every tab and summarizes the sync state, including the latest error. The header has these controls. **Sync now** and **Clear & re-sync** appear only while the client is connected. + +| Control | Description | +| --- | --- | +| 1. **Database list** | Selects the database to show. It appears only when more than one database is attached, for example when your app is open in two browser tabs. | +| 2. **Sync now** | Requests a checkpoint and waits until the client is up to date. Your app must connect with `checkpointMode: 'requests'`. Read [Sync Catch-Up](/client-sdks/advanced/checkpoint-requests). | +| 3. **Clear & re-sync** | Deletes the local data and downloads it again. Hold the button for one second to start it. | + + + **Clear & re-sync** also deletes the local changes in the upload queue. Changes that did not upload, for example writes made offline, are lost. + + +## Sync Status + + + ![Sync Status tab with connection details, download progress, and the upload queue](/images/tools/devtools-sync-status.png) + + +Use the **Sync Status** tab to check the connection, the download progress for each priority, and the local changes that are still waiting to upload. The tab also shows download and upload errors. + +Use **Disconnect** and **Reconnect** to test how your app behaves offline and when it connects again. + +## Data Inspector + + + ![Data Inspector tab with the table list and a SQL query result](/images/tools/devtools-data-inspector.png) + + +Use the **Data Inspector** tab to browse your tables and to run SQL against the local SQLite database in your app. To run a query, press `⌘+Enter` or `Ctrl+Enter`. + +The tables in your schema are SQLite views. The client's sync state is in internal `ps_*` tables, such as `ps_buckets`, `ps_oplog`, and `ps_crud`. + + + Writes in the SQL editor change your local data. A write to one of your schema tables goes into the upload queue, and your connector's `uploadData()` sends it to your backend, like a write from your app. + + +## Buckets + + + ![Buckets tab with a list of buckets, their operations, and their size](/images/tools/devtools-buckets.png) + + +The **Buckets** tab lists the buckets on the client, with the downloaded operations and size of each. Select a bucket to see its operations and rows. + +To also see the total number of operations for each bucket, connect with `diagnostics: true`: + +```typescript +await db.connect(connector, { diagnostics: true }); +``` + +## Streams + + + ![Streams tab with Sync Stream subscriptions and the subscribe form](/images/tools/devtools-streams.png) + + +The **Streams** tab lists your Sync Stream subscriptions, including when each one expires. + +To test a stream, subscribe to it with the form. The form's TTL defaults to 0, so the client removes the stream's data soon after you unsubscribe. Read [Sync Streams](/sync/streams/overview) for more about TTL and priority. + +## Config + + + ![Config tab with connection details and the schema as JSON](/images/tools/devtools-config.png) + + +The **Config** tab shows the connection details, such as the endpoint, user ID, and connection parameters, and your client schema. + +The user ID comes from the `sub` claim of the JWT that your connector returns. + +## Logs + + + ![Logs tab with log records and the level filter](/images/tools/devtools-logs.png) + + +The **Logs** tab shows the PowerSync SDK's log records. It collects records only after DevTools attaches to the database, so earlier records do not appear. diff --git a/tools/devtools/vite.mdx b/tools/devtools/vite.mdx new file mode 100644 index 000000000..d4b07af36 --- /dev/null +++ b/tools/devtools/vite.mdx @@ -0,0 +1,102 @@ +--- +title: "PowerSync DevTools for Vite" +description: "Add PowerSync DevTools to the Vite DevTools dock in a React, Vue, Svelte, or other Vite web app." +sidebarTitle: "Vite" +--- + +The `@powersync/diagnostics/vite` plugin adds a **PowerSync** entry to the [Vite DevTools](https://devtools.vite.dev) dock. It works with any web app that uses Vite and `@powersync/web`, such as React, Vue, and Svelte apps. + +## Requirements + +- `@powersync/web` 2.5.0 or later. +- Vite 7 or later. + +## Set Up DevTools + + + + ```bash + npm install -D @powersync/diagnostics @vitejs/devtools + ``` + + Both setups in the next step require `@vitejs/devtools`. + + + Enable Vite DevTools and add the PowerSync plugin in `vite.config.ts`. On Vite 8.3 or later, we recommend the `devtools` option. On earlier versions, use the `DevTools()` plugin. + + + + ```typescript + import { defineConfig } from 'vite'; + import powersyncDevtools from '@powersync/diagnostics/vite'; + + export default defineConfig({ + devtools: { apply: 'serve' }, + plugins: [powersyncDevtools()] + }); + ``` + + `apply: 'serve'` limits Vite DevTools to the dev server. Without it, Vite DevTools also runs during `vite build`. You can also use `devtools: true`. + + + The plugin works on all supported Vite versions. Before Vite 8.3, it is the only setup, because the `devtools` option does not work on the dev server. + + ```typescript + import { defineConfig } from 'vite'; + import { DevTools } from '@vitejs/devtools'; + import powersyncDevtools from '@powersync/diagnostics/vite'; + + export default defineConfig({ + plugins: [...(await DevTools()), powersyncDevtools()] + }); + ``` + + + + + To show the total number of operations for each bucket in the **Buckets** tab, pass `diagnostics: true` when you connect. + + ```typescript + await db.connect(connector, { diagnostics: true }); + ``` + + + Start the dev server and open your app. The first time, Vite DevTools asks you to trust the browser: + + 1. Click the Vite DevTools dock entry. + 2. Enter the six-digit code from the terminal in the browser, or open the link that the terminal prints. + + You'll do this once for each browser profile. + + + Click the **PowerSync** entry in the dock at the bottom of the page. + + + + + ![Vite DevTools dock with the PowerSync entry open](/images/tools/devtools-vite-dock.png) + + +To see what each tab shows, read [Using DevTools](/tools/devtools/using-devtools). To connect a coding agent, read [MCP Tools](/tools/devtools/mcp). + +## Plugin Options + +| Option | Description | +| --- | --- | +| `title` | The title of the dock entry. The default is `PowerSync`. | + +## Multiple Tabs and Databases + +If your app is open in more than one browser tab, DevTools attaches the database from each tab. To switch between them, use the database list in the DevTools header. The list appears only when more than one database is attached. + +If one page opens more than one PowerSync database, DevTools shows only the first one. + + + ![DevTools header with a list of two attached databases, web-1 and web-2](/images/tools/devtools-multiple-tabs.png) + + +## Troubleshooting + +**The dock has no PowerSync entry.** Check that Vite DevTools is enabled: the `devtools` option (Vite 8.3 or later) or the `DevTools()` plugin. Then restart the dev server. + +**DevTools shows "No PowerSync database attached".** DevTools gets the database from an open app tab. Open your app in a browser that Vite DevTools trusts. DevTools updates when your app opens its database. If the app tab was in the background for a while, reload the app tab to attach the database again. diff --git a/tools/nuxt-inspector.mdx b/tools/nuxt-inspector.mdx deleted file mode 100644 index 8dcc8e3e2..000000000 --- a/tools/nuxt-inspector.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Nuxt DevTools Integration" -description: "A Nuxt DevTools integration for inspecting PowerSync sync status, local data, config, and logs during development." -sidebarTitle: "Nuxt DevTools" ---- - -The `@powersync/nuxt` module includes a PowerSync diagnostics panel that integrates with [Nuxt DevTools](https://devtools.nuxt.com/). It lets you inspect your app's sync state, local SQLite data, and configuration while running in development. - -## Enabling Diagnostics - -Add `powersync: { useDiagnostics: true }` to your `nuxt.config.ts`: - -```typescript nuxt.config.ts -export default defineNuxtConfig({ - modules: ['@powersync/nuxt'], - powersync: { - useDiagnostics: true - }, - vite: { - optimizeDeps: { - exclude: ['@powersync/web'] - }, - worker: { - format: 'es' - } - } -}); -``` - -No changes to your plugin code are needed. When `useDiagnostics: true` is set, `NuxtPowerSyncDatabase` automatically extends your schema with the diagnostics schema, sets up diagnostics recording and logging, and stores the connector internally so the inspector can access it. - -## Accessing the Inspector - - - ![PowerSync Inspector in Nuxt DevTools](/images/nuxt/inspector.png) - - -Open the inspector in one of two ways: - -- **Nuxt DevTools**: open DevTools in your browser and navigate to the PowerSync tab. -- **Direct URL**: navigate to `http://localhost:3000/__powersync-inspector`. - -## Inspector Views - -| View | Description | -| --- | --- | -| **Sync Status** | Real-time connection status, sync progress, upload queue statistics, and error monitoring | -| **Data Inspector** | Browse and search your local SQLite tables | -| **Bucket Inspector** | Browse your buckets and their data | -| **Config Inspector** | View your PowerSync configuration, connection options, and schema | -| **Logs** | Real-time log output with syntax highlighting and search | - -## Known Issues - -The inspector uses `unocss` as a transitive dependency, which can conflict with Tailwind CSS. If you use Tailwind, add the following to your `nuxt.config.ts`: - -```typescript nuxt.config.ts -export default defineNuxtConfig({ - unocss: { - autoImport: false - } -}); -``` diff --git a/tools/overview.mdx b/tools/overview.mdx index 029e8f10e..968cd84af 100644 --- a/tools/overview.mdx +++ b/tools/overview.mdx @@ -32,14 +32,14 @@ sidebarTitle: "Overview" ## DevTools Integrations -IDE and framework integrations for inspecting PowerSync databases and sync state during development. +Inspect the live PowerSync client in your app during development. - - Inspect databases, run SQL queries, and view sync state inside Dart & Flutter DevTools. + + Inspect sync status, local data, and logs in your app. Includes MCP tools for coding agents. - - Inspect sync status, local data, config, and logs inside Nuxt DevTools. + + Inspect databases, run SQL queries, and view sync state inside Dart & Flutter DevTools.