wip devtools

.gitignore

@@ -90,6 +90,7 @@ out
 # Nuxt.js build / generate output
 .nuxt
 dist
+build
 
 # Gatsby files
 .cache/

examples/react/todo/package.json

@@ -3,24 +3,28 @@
   "private": true,
   "version": "0.1.1",
   "dependencies": {
+    "@tanstack/db-devtools": "workspace:*",
     "@tanstack/electric-db-collection": "^0.1.0",
     "@tanstack/query-core": "^5.75.7",
     "@tanstack/query-db-collection": "^0.2.0",
     "@tanstack/react-db": "^0.1.0",
+    "@tanstack/react-db-devtools": "workspace:*",
+    "@tanstack/react-devtools": "^0.3.0",
     "@tanstack/react-router": "^1.125.6",
+    "@tanstack/react-router-devtools": "^1.130.2",
     "@tanstack/react-start": "^1.126.1",
-    "@tanstack/trailbase-db-collection": "^0.1.0",
+    "@tanstack/trailbase-db-collection": "^0.1.2",
     "cors": "^2.8.5",
     "drizzle-orm": "^0.40.1",
     "drizzle-zod": "^0.8.3",
-    "zod": "^4.0.17",
     "express": "^4.19.2",
     "postgres": "^3.4.7",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "tailwindcss": "^4.1.11",
     "trailbase": "^0.7.1",
-    "vite-tsconfig-paths": "^5.1.4"
+    "vite-tsconfig-paths": "^5.1.4",
+    "zod": "^4.0.17"
   },
   "devDependencies": {
     "@eslint/js": "^9.22.0",

examples/react/todo/src/lib/collections.ts

@@ -1,4 +1,5 @@
 import { createCollection } from "@tanstack/react-db"
+import { initializeDbDevtools } from "@tanstack/react-db-devtools"
 import { electricCollectionOptions } from "@tanstack/electric-db-collection"
 import { queryCollectionOptions } from "@tanstack/query-db-collection"
 import { trailBaseCollectionOptions } from "@tanstack/trailbase-db-collection"
@@ -11,13 +12,16 @@ import type { SelectConfig, SelectTodo } from "../db/validation"
 // Create a query client for query collections
 const queryClient = new QueryClient()
 
+// Initialize DB devtools early (idempotent - safe to call multiple times)
+initializeDbDevtools()
+
 // Create a TrailBase client.
 const trailBaseClient = initClient(`http://localhost:4000`)
 
 // Electric Todo Collection
 export const electricTodoCollection = createCollection(
   electricCollectionOptions({
-    id: `todos`,
+    id: `electric-todos`,
     shapeOptions: {
       url: `http://localhost:3003/v1/shape`,
       params: {
@@ -71,7 +75,7 @@ export const electricTodoCollection = createCollection(
 // Query Todo Collection
 export const queryTodoCollection = createCollection(
   queryCollectionOptions({
-    id: `todos`,
+    id: `query-todos`,
     queryKey: [`todos`],
     refetchInterval: 3000,
     queryFn: async () => {
@@ -130,7 +134,7 @@ type Todo = {
 // TrailBase Todo Collection
 export const trailBaseTodoCollection = createCollection(
   trailBaseCollectionOptions<SelectTodo, Todo>({
-    id: `todos`,
+    id: `trailbase-todos`,
     getKey: (item) => item.id,
     schema: selectTodoSchema,
     recordApi: trailBaseClient.records(`todos`),
@@ -149,7 +153,7 @@ export const trailBaseTodoCollection = createCollection(
 // Electric Config Collection
 export const electricConfigCollection = createCollection(
   electricCollectionOptions({
-    id: `config`,
+    id: `electric-config`,
     shapeOptions: {
       url: `http://localhost:3003/v1/shape`,
       params: {
@@ -185,7 +189,7 @@ export const electricConfigCollection = createCollection(
 // Query Config Collection
 export const queryConfigCollection = createCollection(
   queryCollectionOptions({
-    id: `config`,
+    id: `query-config`,
     queryKey: [`config`],
     refetchInterval: 3000,
     queryFn: async () => {
@@ -231,7 +235,7 @@ type Config = {
 // TrailBase Config Collection
 export const trailBaseConfigCollection = createCollection(
   trailBaseCollectionOptions<SelectConfig, Config>({
-    id: `config`,
+    id: `trailbase-config`,
     getKey: (item) => item.id,
     schema: selectConfigSchema,
     recordApi: trailBaseClient.records(`config`),

examples/react/todo/src/routes/__root.tsx

@@ -4,6 +4,10 @@ import {
   Scripts,
   createRootRoute,
 } from "@tanstack/react-router"
+import { TanstackDevtools } from "@tanstack/react-devtools"
+import { TanStackRouterDevtoolsPanel } from "@tanstack/react-router-devtools"
+import { TanStackReactDbDevtoolsPanel } from "@tanstack/react-db-devtools"
+// import { TanStackReactDbDevtools } from "@tanstack/react-db-devtools"
 
 import appCss from "../styles.css?url"
 
@@ -32,6 +36,20 @@ export const Route = createRootRoute({
   component: () => (
     <RootDocument>
       <Outlet />
+      <TanstackDevtools
+        plugins={[
+          {
+            name: "Tanstack Router",
+            render: <TanStackRouterDevtoolsPanel />,
+          },
+          {
+            name: "Tanstack DB",
+            render: <TanStackReactDbDevtoolsPanel />,
+          },
+        ]}
+      />
+      {/* Alternative standalone component */}
+      {/* <TanStackReactDbDevtools position="bottom-right" /> */}
     </RootDocument>
   ),
 })

packages/db-devtools/README.md

@@ -0,0 +1,64 @@
+# @tanstack/db-devtools
+
+Developer tools for TanStack DB that provide real-time insights into your collections, live queries, and transactions.
+
+## Installation
+
+```bash
+npm install @tanstack/db-devtools
+npm install @tanstack/react-db-devtools
+```
+
+## Usage
+
+### With TanStack Devtools (Recommended)
+
+```tsx
+import { TanstackDevtools } from "@tanstack/react-devtools"
+import { TanStackReactDbDevtoolsPanel } from "@tanstack/react-db-devtools"
+
+function App() {
+  return (
+    <TanstackDevtools
+      plugins={[
+        {
+          name: "Tanstack DB",
+          render: <TanStackReactDbDevtoolsPanel />,
+        },
+      ]}
+    />
+  )
+}
+```
+
+### Standalone Component
+
+```tsx
+import { ReactDbDevtools } from "@tanstack/react-db-devtools"
+
+function App() {
+  return (
+    <div>
+      <h1>My App</h1>
+      <ReactDbDevtools position="bottom-right" />
+    </div>
+  )
+}
+```
+
+## Features
+
+- **Collection Monitoring**: View all active collections with real-time status updates
+- **Live Query Insights**: Special handling for live queries with performance metrics
+- **Transaction Tracking**: Monitor all database transactions and their states
+- **Development Only**: Automatically tree-shaken in production builds
+
+## What You Can See
+
+- Collection status, size, and transaction count
+- Live query performance metrics
+- Transaction details and states
+- Real-time data inspection
+- Collection metadata and settings
+
+Collections automatically register themselves with the devtools when created - no additional setup required.

packages/db-devtools/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@tanstack/db-devtools",
+  "version": "0.0.1",
+  "description": "Developer tools for TanStack DB",
+  "author": "tanstack",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TanStack/db.git",
+    "directory": "packages/db-devtools"
+  },
+  "homepage": "https://tanstack.com/db",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "browser": {},
+  "exports": {
+    ".": {
+      "@tanstack/custom-condition": "./src/index.ts",
+      "solid": {
+        "development": "./dist/index.js",
+        "import": "./dist/index.js"
+      },
+      "development": {
+        "import": {
+          "types": "./dist/index.d.ts",
+          "default": "./dist/index.js"
+        },
+        "require": {
+          "types": "./dist/index.d.ts",
+          "default": "./dist/index.cjs"
+        }
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "!src/__tests__"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "premove ./build ./coverage ./dist-ts",
+    "compile": "tsc --build",
+    "test:eslint": "eslint ./src",
+    "test:types": "npm-run-all --serial test:types:*",
+    "test:types:ts53": "node ../../node_modules/typescript53/lib/tsc.js --build",
+    "test:types:ts54": "node ../../node_modules/typescript54/lib/tsc.js --build",
+    "test:types:ts55": "node ../../node_modules/typescript55/lib/tsc.js --build",
+    "test:types:ts56": "node ../../node_modules/typescript56/lib/tsc.js --build",
+    "test:types:ts57": "node ../../node_modules/typescript57/lib/tsc.js --build",
+    "test:types:tscurrent": "tsc --build",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm run test:lib --watch",
+    "test:build": "publint --strict && attw --pack",
+    "lint": "eslint . --fix",
+    "build": "vite build",
+    "build:dev": "tsup --watch"
+  },
+  "dependencies": {
+    "@tanstack/db": "workspace:*",
+    "@tanstack/react-table": "^8.13.2",
+    "@tanstack/react-virtual": "^3.0.0",
+    "@tanstack/solid-db": "workspace:*",
+    "@tanstack/solid-table": "^8.21.3",
+    "@tanstack/solid-virtual": "^3.13.12",
+    "@types/prismjs": "^1.26.5",
+    "prismjs": "^1.30.0"
+  },
+  "devDependencies": {
+    "@kobalte/core": "^0.13.4",
+    "@solid-primitives/keyed": "^1.2.2",
+    "@solid-primitives/resize-observer": "^2.0.26",
+    "@solid-primitives/storage": "^1.3.11",
+    "@tanstack/match-sorter-utils": "^8.19.4",
+    "clsx": "^2.1.1",
+    "goober": "^2.1.16",
+    "npm-run-all2": "^5.0.0",
+    "solid-js": "^1.9.5",
+    "solid-transition-group": "^0.2.3",
+    "superjson": "^2.2.1",
+    "tsup-preset-solid": "^2.2.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-solid": "^2.11.6"
+  }
+}