diff --git a/client-sdks/reference/flutter.mdx b/client-sdks/reference/flutter.mdx index df668a3e2..19092803f 100644 --- a/client-sdks/reference/flutter.mdx +++ b/client-sdks/reference/flutter.mdx @@ -425,7 +425,7 @@ See [ORM Support](/client-sdks/orms/flutter-orm-support) for details. ## Troubleshooting -Use the [Dart & Flutter DevTools extension](/tools/dart-devtools-extension) to inspect live databases, run SQL queries, and view sync status without leaving your IDE. Available from `powersync` v2.1.0 in debug builds. +Use the [Dart & Flutter DevTools extension](/tools/devtools/dart) to inspect live databases, run SQL queries, and view sync status without leaving your IDE. Available from `powersync` v2.1.0 in debug builds. See [Troubleshooting](/debugging/troubleshooting) for pointers to debug common issues. diff --git a/docs.json b/docs.json index 1422f7905..b90e6331d 100644 --- a/docs.json +++ b/docs.json @@ -332,8 +332,7 @@ "client-sdks/reference/flutter", "client-sdks/frameworks/flutter-web-support", "client-sdks/orms/flutter-orm-support", - "client-sdks/reference/flutter-api", - "tools/dart-devtools-extension" + "client-sdks/reference/flutter-api" ] }, { @@ -537,7 +536,8 @@ "pages": [ "tools/devtools/vite", "tools/devtools/nuxt", - "tools/devtools/node" + "tools/devtools/node", + "tools/devtools/dart" ] }, "tools/devtools/using-devtools", @@ -1449,6 +1449,10 @@ { "source": "/resources/usage-and-billing-faq", "destination": "/resources/usage-and-billing/usage-and-billing-faq" + }, + { + "source": "/tools/dart-devtools-extension", + "destination": "/tools/devtools/dart" } ], "appearance": { diff --git a/images/tools/dart-devtools-overview.png b/images/tools/dart-devtools-overview.png deleted file mode 100644 index 23714ee17..000000000 Binary files a/images/tools/dart-devtools-overview.png and /dev/null differ diff --git a/images/tools/dart-devtools-sql-console.png b/images/tools/dart-devtools-sql-console.png deleted file mode 100644 index 8436a0253..000000000 Binary files a/images/tools/dart-devtools-sql-console.png and /dev/null differ diff --git a/images/tools/devtools-dart.png b/images/tools/devtools-dart.png new file mode 100644 index 000000000..948a37079 Binary files /dev/null and b/images/tools/devtools-dart.png differ diff --git a/tools/dart-devtools-extension.mdx b/tools/dart-devtools-extension.mdx deleted file mode 100644 index 413162de8..000000000 --- a/tools/dart-devtools-extension.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: "Dart & Flutter DevTools Extension" -description: "A Dart & Flutter DevTools extension for inspecting PowerSync databases, running SQL queries, and viewing sync status during development." -sidebarTitle: "Dart & Flutter DevTools" ---- - -The PowerSync DevTools extension adds a Database Inspector panel to [Dart & Flutter DevTools](https://docs.flutter.dev/tools/devtools/overview). It gives you a view into an open `PowerSyncDatabase` instance while your app is running during development. The Overview helps you see how the client is connected, whether there are any sync issues, and details about each Sync Stream. You can open the same session in the [Sync Diagnostics Client](/tools/diagnostics-client) for further sync activity details. The SQL Console is for running SQL and sampling rows from the on-device SQLite database. - -The extension is included in the `powersync` package from v2.1.0 and activates automatically when a `PowerSyncDatabase` is opened. It is disabled in release builds. - -## Opening the Extension - -First, open DevTools: - -- In **VS Code**, launch your app in debug mode, then run the **Dart: Open DevTools in Browser** command from the command palette. -- In **Android Studio / Intellij**, click the **Flutter DevTools** button in the run toolbar. -- For apps launched from the command line, see [these instructions](https://docs.flutter.dev/tools/devtools/cli). - -In DevTools, A **powersync** tab appears in the DevTools tab bar alongside the standard panels. If you have multiple databases open, use the dropdown in the top-right corner to switch between them. - -## Overview - -The Overview tab shows the current state of your database and sync connection. - - - ![Overview tab of the PowerSync Dart & Flutter DevTools extension](/images/tools/dart-devtools-overview.png) - - -**Database Status** displays: - -- **Database path** — the full path to the SQLite file on disk, with a copy button. Useful when you need to locate the file for [offline inspection](/maintenance-ops/client-database-diagnostics). -- **Service URL** — the PowerSync Service endpoint your app is connected to. -- **User ID** — the authenticated user's ID, with a **Show token** option to reveal the current JWT and an **Open in Sync Diagnostics Client** link to the [Sync Diagnostics Client](/tools/diagnostics-client). -- **Sync status** — a summary of the connection state and any reported issues. - -Sync Streams lists each active stream with its configuration and sync state, including parameters, priority, last synced timestamp, and eviction time. - -## SQL Console - -The SQL Console lets you run queries against your app's SQLite database. - - - ![SQL Console tab of the PowerSync Dart & Flutter DevTools extension](/images/tools/dart-devtools-sql-console.png) - - -Type any SQL into the editor and click **Execute** to run it. Results appear in a paginated table below. - -The **Or select from:** row shows shortcut buttons for every table in the database. These include both your schema tables and the internal PowerSync tables (`ps_crud`, `ps_oplog`, `ps_untyped`, `ps_buckets`). - - - The SQL Console runs queries against the local SQLite database only. It does not send queries to your backend source database. - diff --git a/tools/devtools-overview.mdx b/tools/devtools-overview.mdx index 695a24a30..9760f26e2 100644 --- a/tools/devtools-overview.mdx +++ b/tools/devtools-overview.mdx @@ -4,9 +4,9 @@ description: "Inspect the live state of your app's PowerSync client during devel sidebarTitle: "Overview" --- - - PowerSync DevTools is currently available for [Vite](/tools/devtools/vite), [Nuxt](/tools/devtools/nuxt), and [Node.js](/tools/devtools/node) apps. - + + PowerSync DevTools is currently available for [Vite](/tools/devtools/vite), [Nuxt](/tools/devtools/nuxt), [Node.js](/tools/devtools/node) and [Dart/Flutter](/tools/devtools/dart) apps. + Use PowerSync DevTools to: @@ -32,7 +32,7 @@ Your Vite or Nuxt dev server serves DevTools. In a Node.js app, your app process ```mermaid flowchart LR - App["Your app
(browser tab or Node process)"] -- "live database" --> Host["Dev server
(Vite, Nuxt, or your Node app)"] + App["Your app
(browser tab or running process)"] -- "live database" --> Host["Dev server"] Host --> UI["DevTools window"] Host --> Agent["Coding agent
(MCP)"] ``` @@ -53,6 +53,10 @@ DevTools reads from the database that your app has open, so it shows the same da Node.js apps that use `@powersync/node`. + + + Any Dart or Flutter app. + diff --git a/tools/devtools/dart.mdx b/tools/devtools/dart.mdx new file mode 100644 index 000000000..c093bca9a --- /dev/null +++ b/tools/devtools/dart.mdx @@ -0,0 +1,23 @@ +--- +title: "PowerSync DevTools for Dart and Flutter" +description: "Launch PowerSync DevTools in the Dart and Flutter DevTools view you already know!" +sidebarTitle: "Dart & Flutter" +--- + +The PowerSync SDK contributes a DevTools extension to [Dart & Flutter DevTools](https://docs.flutter.dev/tools/devtools/overview). No additional dependencies or setup is required to launch PowerSync DevTools. The extension is included in the `powersync` package from v2.6.0 and activates automatically when a `PowerSyncDatabase` is opened. It is disabled in release builds. + +## Open the Extension + +First, open DevTools: + +- In **VS Code**, launch your app in debug mode, then run the **Dart: Open DevTools in Browser** command from the command palette. +- In **Android Studio / Intellij**, click the **Flutter DevTools** button in the run toolbar. +- For apps launched from the command line, see [these instructions](https://docs.flutter.dev/tools/devtools/cli). + +In DevTools, a **powersync** tab appears in the DevTools tab bar alongside the standard panels. If you have multiple databases open, use the dropdown in the top-right corner to switch between them. + + + ![Screenshot of the PowerSync Dart & Flutter DevTools extension](/images/tools/devtools-dart.png) + + +For a complete overview of what PowerSync DevTools has to offer, see [Using DevTools](/tools/devtools/using-devtools). diff --git a/tools/devtools/mcp.mdx b/tools/devtools/mcp.mdx index b735de032..2d825ec59 100644 --- a/tools/devtools/mcp.mdx +++ b/tools/devtools/mcp.mdx @@ -17,6 +17,7 @@ PowerSync DevTools exposes MCP (Model Context Protocol) tools that let a coding | 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 | +| Dart and Flutter | Use the MCP server [built in to the Dart SDK](https://docs.flutter.dev/ai/tools#dart-and-flutter-mcp-server) instead. | Nuxt DevTools 3 does not have an MCP endpoint. diff --git a/tools/devtools/using-devtools.mdx b/tools/devtools/using-devtools.mdx index 6a8fbc500..298aab01e 100644 --- a/tools/devtools/using-devtools.mdx +++ b/tools/devtools/using-devtools.mdx @@ -4,7 +4,7 @@ description: "What each PowerSync DevTools tab shows, and the sync actions you c 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). +PowerSync DevTools has the same tabs in Vite, Nuxt, Node.js, and Dart/Flutter. To set it up, start with the [overview](/tools/devtools-overview). ## Header and Status Bar @@ -16,8 +16,8 @@ The status bar stays visible on every tab and summarizes the sync state, includi | 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). | +| 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 or opens more than one database. | +| 2. **Sync now** | Requests a checkpoint and waits until the client is up to date. Your app must connect with the `requests` checkpoint mode. 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. | @@ -56,7 +56,7 @@ The tables in your schema are SQLite views. The client's sync state is in intern 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`: +To also see the total number of operations for each bucket, enable diagnostics. Dart and Flutter apps enable them by default outside release builds. In JavaScript apps, connect with `diagnostics: true`: ```typescript await db.connect(connector, { diagnostics: true }); diff --git a/tools/overview.mdx b/tools/overview.mdx index 968cd84af..7d2e662d1 100644 --- a/tools/overview.mdx +++ b/tools/overview.mdx @@ -38,8 +38,4 @@ Inspect the live PowerSync client in your app during development. Inspect sync status, local data, and logs in your app. Includes MCP tools for coding agents. - - - Inspect databases, run SQL queries, and view sync state inside Dart & Flutter DevTools. -