docs: add PowerSync DevTools guides for Vite, Nuxt, and Node.js by khawarizmus · Pull Request #672 · powersync-ja/powersync-docs

khawarizmus · 2026-09-30T06:22:33Z

Summary

Adds docs for the new PowerSync DevTools.

Changes

Rewrote tools/devtools-overview. It explains what DevTools is and how it works, and links to one setup page per environment.
New setup pages:
- tools/devtools/vite: Vite 7 and Vite 8, in tabs.
- tools/devtools/nuxt: Nuxt DevTools 3 and 4, in tabs, with a migration guide from @powersync/nuxt 0.x.
- tools/devtools/node: Node.js apps.
New shared pages:
- tools/devtools/using-devtools: what each DevTools tab shows.
- tools/devtools/mcp: how coding agents connect to DevTools with MCP.
Removed: the old tools/nuxt-inspector page. Its URL now redirects to tools/devtools/nuxt.
Updated the Nuxt SDK page: it now uses PowerSyncDatabase, because NuxtPowerSyncDatabase is removed.
Updated links: in tools/overview and tools/ai-tools.

This PR should be merged after powersync-ja/powersync-js#1094 is released, so we can add minimum versions of @powersync/web, @powersync/nuxt and @powersync/node.

AI Disclosure

The docs were generated with the help of Claude. Modified and reviewed manually.

…leshooting

mintlify · 2026-09-30T06:22:37Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
powersync	🟢 Ready	View Preview	Oct 1, 2026, 7:54 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

claude · 2026-09-30T06:30:43Z

+        Nuxt DevTools 4 is in beta. It runs on Vite DevTools and needs Vite 8.1.5 or later. Nuxt 4.5 includes a compatible Vite version.
+
+        Nuxt 4 depends on Nuxt DevTools 3. To use version 4, install it 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


The Nuxt DevTools 4 beta status, the "Vite 8.1.5 or later" floor, and the 4.0.0-beta.2 override pin aren't backed by anything in the cited implementation PR (powersync-js#1094) — that PR's own testing notes and lockfile only reference @nuxt/devtools@3.4.1. Since this is a third-party prerelease version that can go stale quickly, either verify it against the actual @nuxt/devtools release history before publishing, or add a verification TODO like the ones already used elsewhere in this PR for unconfirmed version numbers.

claude · 2026-09-30T06:30:52Z

+
+## Requirements
+
+- `@powersync/node`. {/* TODO: Add the minimum version after the release. It needs the `diagnostics` sync option and the `connector` accessor from `@powersync/common`. */}


Unlike the equivalent requirement bullets on the Vite and Nuxt pages (which give a placeholder version before the TODO), this one has no version qualifier at all, so once the MDX comment is stripped the rendered bullet just reads "@powersync/node." with no information. Consider adding a placeholder like the other two pages do, e.g. "@powersync/node (version TBC)." so the list item isn't empty of content.

claude · 2026-09-30T06:30:56Z

Couldn't run Vale or the link checker in this environment (CI check results and vale/gh pr checks were blocked by sandbox permissions), so those results aren't reflected here — only the manual accuracy/clarity review above.

benitav · 2026-09-30T13:19:13Z

+
+    ```typescript
+    import { PowerSyncDatabase } from '@powersync/node';
+    import { enablePowerSyncDiagnostics } from '@powersync/diagnostics/node';


This was pointed out by Claude locally, from what I can see it may be valid feedback:

@powersync/diagnostics is installed with -D, but the example imports it statically at the top of the file. A production install that skips dev dependencies (npm ci --omit=dev) will fail on startup, even though the call is behind the NODE_ENV check. Can we switch to a dynamic import inside the check, and add one sentence saying why?

if (process.env.NODE_ENV !== 'production') { const { enablePowerSyncDiagnostics } = await import('@powersync/diagnostics/node'); const devtools = await enablePowerSyncDiagnostics(db); console.log(`PowerSync DevTools: ${devtools.signInUrl}`); }

This was fixed in both repos.

benitav · 2026-09-30T13:22:07Z

-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.
+PowerSync DevTools shows the sync status, buckets, Sync Stream subscriptions, local SQLite data, schema, and logs of the PowerSync client in your app. You can also run SQL queries and sync actions. Coding agents can read the same data 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.


adds nothing to a production build. is this really true for Node.js, where it seems the tools have to explicitly be enabled for dev only?

Yes with the changes you suggested above this becomes true even for Node js apps where a production install doesn't include the package, and the app never loads it.

benitav · 2026-09-30T13:27:04Z

+## Requirements
+
+- `@powersync/web` 2.5.0 or later. {/* TODO: Confirm the version after the release. */}
+- Vite 7, or Vite 8.3 or later.


Vite 8.3 is inconsistent with Vite 8.1.5 mentioned on the Nuxt page - seems a bit odd since we say the Nuxt version runs on this one. Just want to confirm.

Both numbers were correct, but they meant different things. Vite 8.3 is the first version with the devtools config option that plain Vite apps use. Nuxt DevTools 4 needs Vite 8.1.5 or later, and on versions before 8.3 it adds Vite DevTools itself, so Nuxt users never touch that option. To avoid the confusion, we now say "needs Nuxt 4.5 or later" and we give no Vite version.

benitav · 2026-09-30T13:40:46Z

+|---|---|
+| 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. |
+| **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). |
+| **Clear & re-sync** | Deletes the local data and downloads it again. Hold the button for one second to start it. |


I think we should point out that this will also clear data still in the upload Queue in case they made writes (e.g. while offline) that they expect to still sync

Same goes for the corresponding command on the MCP page

Agreed, added a warning under the header table.

benitav · 2026-09-30T13:44:06Z

+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`.
+
+<Warning>
+Writes in the SQL editor change your local data. A write to one of your schema tables goes into the upload queue, like a write from your app.


Suggested change

Writes in the SQL editor change your local data. A write to one of your schema tables goes into the upload queue, like a write from your app.

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.

per https://journeyapps.slack.com/archives/C043VUKN35K/p1790775418141989?thread_ts=1788966311.059039&cid=C043VUKN35K

Used your wording here

benitav · 2026-10-01T07:45:54Z

 ---

-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.
+PowerSync DevTools shows the sync status, buckets, Sync Stream subscriptions, local SQLite data, schema, and logs of the PowerSync client in your app. You can also run SQL queries and sync actions. Coding agents can read the same data through [MCP tools](/tools/devtools/mcp) when you use Vite, Nuxt DevTools 4, or Node.js.


Nit: Rather than describing what the devtools show, it would be more useful to readers to describe what the devtools help with - i.e. explain the use cases behind these things. So as an example, rather than just saying "they show local data" explain what that means for a user, e.g. they allow you to inspect the live local data of a client (I'm not sure if this is the best summary). Then a reader can more easily grok if they'd be useful for their use case or not.

…warning, Nuxt 4.5 requirement # Conflicts: # tools/devtools/node.mdx # tools/devtools/using-devtools.mdx

khawarizmus added 2 commits September 30, 2026 13:50

feature: restructured and documented PowerSync devtools

d72e88e

docs(devtools): add screenshots, Nuxt DevTools 4 MCP setup, and troub…

2df8d0c

…leshooting

khawarizmus requested review from benitav and simolus3 September 30, 2026 06:22

mintlify Bot deployed to staging September 30, 2026 06:23 View deployment

claude Bot reviewed Sep 30, 2026

View reviewed changes

Minor wording polish according to repo writing standards

cbb9fc6

mintlify Bot deployed to staging September 30, 2026 13:16 View deployment

benitav reviewed Sep 30, 2026

View reviewed changes

benitav reviewed Oct 1, 2026

View reviewed changes

docs(devtools): address review: dynamic Node import, Clear & re-sync …

78aeb52

…warning, Nuxt 4.5 requirement # Conflicts: # tools/devtools/node.mdx # tools/devtools/using-devtools.mdx

mintlify Bot deployed to staging October 1, 2026 07:54 View deployment


		## Requirements

		- `@powersync/node`. {/* TODO: Add the minimum version after the release. It needs the `diagnostics` sync option and the `connector` accessor from `@powersync/common`. */}

	Writes in the SQL editor change your local data. A write to one of your schema tables goes into the upload queue, like a write from your app.
	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.

Conversation

khawarizmus commented Sep 30, 2026

Summary

Changes

AI Disclosure

Uh oh!

mintlify Bot commented Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude Bot Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

claude Bot commented Sep 30, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mintlify Bot commented Sep 30, 2026 •

edited

Loading