@powersync/diagnostics 0.0.0-dev-20261020125654 → 0.0.0-dev-20261113122937
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -2
- package/dist/devtools/assets/powersync-CHeJS2lE.js +184 -0
- package/dist/devtools/assets/powersync-lB_i3nJt.css +1 -0
- package/dist/devtools/powersync.html +24 -0
- package/dist/rozenite.json +14 -0
- package/lib/src/agent.d.ts +3 -1
- package/lib/src/agent.js +36 -8
- package/lib/src/agent.js.map +1 -1
- package/lib/src/client.js +4 -4
- package/lib/src/client.js.map +1 -1
- package/lib/src/definition.js +11 -17
- package/lib/src/definition.js.map +1 -1
- package/lib/src/js-agent.d.ts +6 -13
- package/lib/src/js-agent.js +23 -10
- package/lib/src/js-agent.js.map +1 -1
- package/lib/src/node.d.ts +1 -1
- package/lib/src/node.js +2 -2
- package/lib/src/node.js.map +1 -1
- package/lib/src/page.js +2 -3
- package/lib/src/page.js.map +1 -1
- package/lib/src/react-native/agent-tools.d.ts +3 -0
- package/lib/src/react-native/agent-tools.js +137 -0
- package/lib/src/react-native/agent-tools.js.map +1 -0
- package/lib/src/react-native/protocol.d.ts +22 -0
- package/lib/src/react-native/protocol.js +5 -0
- package/lib/src/react-native/protocol.js.map +1 -0
- package/lib/src/react-native/usePowerSyncDevTools.d.ts +7 -0
- package/lib/src/react-native/usePowerSyncDevTools.js +56 -0
- package/lib/src/react-native/usePowerSyncDevTools.js.map +1 -0
- package/lib/src/react-native.d.ts +7 -0
- package/lib/src/react-native.js +8 -0
- package/lib/src/react-native.js.map +1 -0
- package/lib/src/rpc-types.d.ts +1 -1
- package/lib/src/tools.d.ts +19 -0
- package/lib/src/tools.js +24 -0
- package/lib/src/tools.js.map +1 -0
- package/lib/tsconfig.tsbuildinfo +1 -1
- package/package.json +37 -13
- package/src/agent.ts +45 -17
- package/src/client.ts +4 -5
- package/src/definition.ts +11 -17
- package/src/js-agent.ts +33 -27
- package/src/node.ts +3 -3
- package/src/page.ts +2 -4
- package/src/react-native/agent-tools.ts +148 -0
- package/src/react-native/protocol.ts +33 -0
- package/src/react-native/usePowerSyncDevTools.ts +59 -0
- package/src/react-native.ts +14 -0
- package/src/rpc-types.ts +1 -1
- package/src/tools.ts +35 -0
package/README.md
CHANGED
|
@@ -9,8 +9,9 @@ One implementation runs in several hosts:
|
|
|
9
9
|
| A Vite app (React, Vue, Svelte, …) with Vite DevTools | `@powersync/diagnostics/vite` | A **PowerSync** dock in Vite DevTools, and MCP tools at `/__devtools/__mcp` |
|
|
10
10
|
| A Nuxt app | [`@powersync/nuxt`](https://github.com/powersync-ja/powersync-js/tree/main/packages/nuxt) with `useDiagnostics: true` | A **PowerSync** tab or dock in Nuxt DevTools |
|
|
11
11
|
| A node app (`@powersync/node`) | `@powersync/diagnostics/node` | A DevTools window served by your process, and MCP tools at `/__mcp` |
|
|
12
|
+
| A React Native app (`@powersync/react-native`) | `@powersync/diagnostics/react-native` with [Rozenite](https://www.rozenite.dev/) | A **PowerSync** panel in React Native DevTools, and Rozenite agent tools |
|
|
12
13
|
|
|
13
|
-
The process that runs your app also serves the DevTools window. You start nothing else.
|
|
14
|
+
The process that runs your app (or Metro, for React Native) also serves the DevTools window. You start nothing else.
|
|
14
15
|
|
|
15
16
|
The hosts above run in development only, and nothing from them goes into a production build.
|
|
16
17
|
|
|
@@ -71,6 +72,50 @@ Your process serves the DevTools window on a random free port. Open the printed
|
|
|
71
72
|
|
|
72
73
|
Options: `port` (default: a random free port), `host`, `auth` (default `true`), `open` (open the browser, default `false`), `sdk` and `id` (labels in the UI), `mcp` (see [MCP](#mcp)).
|
|
73
74
|
|
|
75
|
+
## React Native
|
|
76
|
+
|
|
77
|
+
PowerSync DevTools run as a [Rozenite](https://www.rozenite.dev/) plugin, a panel in React Native DevTools. Install:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pnpm add -D @powersync/diagnostics @rozenite/metro @rozenite/plugin-bridge @rozenite/agent-bridge
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Install them as direct dependencies of the app. Rozenite finds the plugin among those.
|
|
84
|
+
|
|
85
|
+
Enable Rozenite in Metro:
|
|
86
|
+
|
|
87
|
+
```js
|
|
88
|
+
// metro.config.js
|
|
89
|
+
const { getDefaultConfig } = require('expo/metro-config'); // or '@react-native/metro-config'
|
|
90
|
+
const { withRozenite } = require('@rozenite/metro');
|
|
91
|
+
|
|
92
|
+
module.exports = withRozenite(getDefaultConfig(__dirname), {
|
|
93
|
+
enabled: process.env.WITH_ROZENITE === 'true',
|
|
94
|
+
projectType: 'expo' // for Expo apps with app.config.ts or app.config.js
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Rozenite detects Expo only from an `app.json`. Without `projectType`, an Expo app with `app.config.ts` gets React Native DevTools without the Rozenite tab.
|
|
99
|
+
|
|
100
|
+
Call the hook once, in a component that stays mounted, such as the root layout:
|
|
101
|
+
|
|
102
|
+
```tsx
|
|
103
|
+
import { usePowerSyncDevTools } from '@powersync/diagnostics/react-native';
|
|
104
|
+
|
|
105
|
+
usePowerSyncDevTools(db);
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The hook is a no-op in production builds, and bundlers leave its code out. For per-bucket download totals, connect with `db.connect(connector, { diagnostics: __DEV__ })`.
|
|
109
|
+
|
|
110
|
+
Start the app with `WITH_ROZENITE=true` (for example `WITH_ROZENITE=true npx expo run:ios`), open React Native DevTools (press `j` in the Metro terminal), select **Rozenite**, then **PowerSync**.
|
|
111
|
+
|
|
112
|
+
Coding agents use the same tools through Rozenite's agent CLI, under the `powersync/diagnostics` domain:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npx rozenite agent powersync/diagnostics status
|
|
116
|
+
npx rozenite agent powersync/diagnostics query --sql "SELECT * FROM ps_buckets"
|
|
117
|
+
```
|
|
118
|
+
|
|
74
119
|
## Your own host
|
|
75
120
|
|
|
76
121
|
A page that opens the database itself and shows DevTools in its own iframe, such as the PowerSync Dashboard, builds the integration and hands it to the frame:
|
|
@@ -92,9 +137,11 @@ The port can run any SQL and read the sync token, so `attachIframe` only hands i
|
|
|
92
137
|
|
|
93
138
|
**Clear & re-sync** in DevTools deletes the local rows, which is slow on a large database. A host with a throwaway client, like the PowerSync Dashboard, can pass `attachIframe` a wrapper whose `action` handles `clearData` itself and whose other methods call the integration's. Write each method out, because `{ ...integration }` copies none of them and TypeScript does not catch it. Do not delete a real app's database files, because the client would get a new client id. `disconnectAndClear()` keeps the existing one.
|
|
94
139
|
|
|
140
|
+
A host that has the deployed Sync Config, like the PowerSync Dashboard, can add its Sync Streams to what its wrapper's `getInfo` returns, as `streamDefinitions: [{ name, parameters }]`. The Streams tab then suggests them in its subscribe form and shows the parameters each one reads.
|
|
141
|
+
|
|
95
142
|
## MCP
|
|
96
143
|
|
|
97
|
-
Every host exposes the same tools. Names are `powersync_<function>`. Arguments are positional, `arg0` first:
|
|
144
|
+
Every host exposes the same tools. Names are `powersync_<function>`. Arguments are positional, `arg0` first. React Native has no MCP endpoint: the same tools are Rozenite agent tools (`query`, `schema`, `info`, `status`, `upload-queue`, `action`) with named arguments, for the one database passed to the hook. See [React Native](#react-native).
|
|
98
145
|
|
|
99
146
|
| Tool | Arguments | Returns |
|
|
100
147
|
| ------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
@@ -129,6 +176,7 @@ curl -X POST http://localhost:<port>/__mcp \
|
|
|
129
176
|
- `@powersync/web >= 2.5` for browser apps and the `agent` entry, and `@powersync/node >= 1.2` for node apps. Earlier versions drop the connector once the database connects, so DevTools cannot reconnect the client.
|
|
130
177
|
- Vite DevTools for the dock: Vite `>= 8.3` with `devtools: true`, or the `@vitejs/devtools` plugin on Vite 7.
|
|
131
178
|
- Node `>= 20.16` for the node entry.
|
|
179
|
+
- React Native `>= 0.76` and Rozenite `>= 2.5` for the `react-native` entry.
|
|
132
180
|
|
|
133
181
|
## Related packages
|
|
134
182
|
|