Repository navigation
Add PowerSync DevTools setup page for React Native - #755
khawarizmus wants to merge 4 commits into
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
|
||
| | Tool | Returns | | ||
| | --- | --- | | ||
| | `query` | The result of a read-only SQL query against the local database. | |
There was a problem hiding this comment.
The query tool isn't read-only: agent-tools.ts doesn't mark queryTool with readOnly: true (unlike schema/info/status/upload-queue), and the sibling MCP page explicitly warns "powersync_query can change data." Drop "read-only" here, e.g. "The result of a SQL query against the local database. Like the MCP query tool, it can also change data."
There was a problem hiding this comment.
This was a bug in our implementation affecting Node and RN. I have fixed the bug, so query now writes on every platform.
| <Warning> | ||
| `action` with `clearData` deletes the local data, including the local changes in the upload queue, and downloads the data again. | ||
| </Warning> |
There was a problem hiding this comment.
Since the page says these tools "match the MCP tools," the warning should carry the same two cautions the MCP page gives for the equivalent tools: query can change data, and info returns the live JWT (the MCP page tells readers to give these tools only to agents they trust). Only the clearData risk is covered here.
There was a problem hiding this comment.
The warning now says that query can change data, that writes go through the upload queue, and to give these tools only to agents you trust. It still covers clearData.
| npm install -D @powersync/diagnostics @rozenite/metro @rozenite/plugin-bridge @rozenite/agent-bridge | ||
| ``` | ||
|
|
||
| Add the packages to the dev dependencies in your app's own `package.json`. Rozenite looks for plugins only in the packages listed there. In a monorepo, it does not find `@powersync/diagnostics` if only a shared package lists it. |
There was a problem hiding this comment.
The monorepo failure mode ("it does not find @powersync/diagnostics if only a shared package lists it") isn't stated in the source PR (powersync-js#1185) or the diagnostics README, which only say to install as a direct dependency. This is a specific, falsifiable behavior claim about a third-party tool — verify it against Rozenite's actual plugin-discovery behavior before publishing, or soften to avoid asserting the specific monorepo failure mode.
There was a problem hiding this comment.
This was verified against Rozenite 2.5.0. Its plugin scan (@rozenite/middleware) reads only dependencies and devDependencies from the app's own package.json, so a plugin listed only in a shared package isn't found.
| </Tab> | ||
| </Tabs> | ||
|
|
||
| In the Metro output, `[Rozenite] Loaded 1 plugin(s): @powersync/diagnostics` confirms that Rozenite found the plugin. |
There was a problem hiding this comment.
This exact Metro log line isn't in the source PR, the diagnostics README, or the demo READMEs. Confirm the literal text ([Rozenite] Loaded 1 plugin(s): @powersync/diagnostics) against a real run before publishing — an exact log string that doesn't match what readers see undermines the troubleshooting signal.
There was a problem hiding this comment.
Removed. The line is accurate, since it was seen in a real run, but readers don't need it to finish the setup.
| 1. Run `npx rozenite skills show core` and `npx rozenite skills show cli` to learn how the CLI works. | ||
| 2. Run `npx rozenite agent powersync/diagnostics` to list the PowerSync tools. Add `--help` after a tool name to see its arguments. | ||
| 3. Call the `status` and `upload-queue` tools, and tell me the sync state. | ||
| 4. When you finish, run `npx rozenite agent session stop`. |
There was a problem hiding this comment.
rozenite skills show core, rozenite skills show cli, and rozenite agent session stop aren't confirmed anywhere in powersync-js#1185 — only npx rozenite agent powersync/diagnostics <tool> is shown there. Since readers paste this prompt verbatim into a coding agent, verify these Rozenite CLI subcommands actually exist before publishing (or add a TODO per the verification workflow if they can't be confirmed yet).
There was a problem hiding this comment.
Verified against Rozenite 2.5.0. npx rozenite skills list includes core and cli. Rozenite's agent docs document rozenite agent session stop, and it was used in our testing.
| **React Native DevTools has no Rozenite tab.** Check these causes: | ||
|
|
||
| - Metro started without `WITH_ROZENITE=true`. | ||
| - Your Expo app uses `app.config.ts` or `app.config.js`, and `projectType: 'expo'` is not set. If `curl http://localhost:8081/json/list` returns a `devtoolsFrontendUrl` that starts with `/debugger-frontend/` instead of `/rozenite/`, Rozenite is not active. |
There was a problem hiding this comment.
The curl .../json/list check and the devtoolsFrontendUrl field/path values (/debugger-frontend/ vs. /rozenite/) aren't confirmed by the source PR or any other cited material. Verify this against a real Metro instance before publishing, since a wrong field name or path would send readers down the wrong troubleshooting path.
There was a problem hiding this comment.
Verified against a running Metro with Rozenite. That case was hit and recorded while testing the implementation.
| "pages": [ | ||
| "tools/devtools/vite", | ||
| "tools/devtools/nuxt", | ||
| "tools/devtools/react-native", |
There was a problem hiding this comment.
This places React Native before Capacitor in the sidebar, but the overview page added in this same PR orders the platforms Vite, Nuxt, Capacitor, React Native, Node.js, Dart/Flutter (in both the <Note> and the <CardGroup>), and using-devtools.mdx follows the same order. Move tools/devtools/react-native after tools/devtools/capacitor to match.
There was a problem hiding this comment.
React Native above Capacitor in the sidebar was intended. I updated the "Overview" page and "Using DevTools" page to use the same order.
|
|
||
| ## Agent Tools | ||
|
|
||
| In React Native apps, coding agents use the [Rozenite agent CLI](https://www.rozenite.dev/docs/agent/overview) instead of an MCP endpoint. The hook registers PowerSync tools that let an agent query the local database of your app, read its sync status, and run sync actions. The tools are in the `powersync/diagnostics` domain, for example `npx rozenite agent powersync/diagnostics status`. |
There was a problem hiding this comment.
saying "instead of an MCP endpoint" is a bit random because we're not mentioning MCP before this? The flow here for RN users is also not great. We have the MCP tools page but now we already have 2 platforms that don't really use those MCP tools but have an alternative (Dart and RN). So a RN user might go to the MCP page but this "Agent Tools" section is actually what they need. I think that MCP page should either be a broader Agent tools page that explains how agents can interact with the devtools on each platform, or we can't keep a global page like that anymore (since the mechanism is too different across platforms) and for each platform keep a section like this.
This PR Documents PowerSync DevTools for React Native and Expo apps, added in powersync-ja/powersync-js#1185. The PowerSync panel runs in React Native DevTools as a Rozenite plugin. AI coding agents can use the Rozenite agent CLI.
Changes
tools/devtools/react-native.mdxusePowerSyncDevToolshook, how to open the paneldocs.json), above CapacitorBefore merging
@powersync/diagnosticsand@powersync/react-native. Then remove the TODOs on the page.Claude code was used to plan and draft the docs.