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"
+ }
+}