feat: basic json-render implementation

Author: antfu

docs/kit/dock-system.md

@@ -8,14 +8,15 @@ Dock entries are the primary way for users to interact with your DevTools integr
 
 ## Entry Types
 
-DevTools Kit supports four types of dock entries:
+DevTools Kit supports five types of dock entries:
 
 | Type | Description | Use Case |
 |------|-------------|----------|
 | `iframe` | Displays your UI in an iframe panel | Full-featured UIs, dashboards, data visualization |
 | `action` | Button that triggers client-side scripts | Inspectors, toggles, one-time actions |
 | `custom-render` | Renders directly in the user's app DOM | When you need direct DOM access or framework integration |
 | `launcher` | Actionable setup card shown in panel | Run one-time setup tasks before showing other tools |
+| `json-render` | Renders UI from a JSON spec — no client code needed | Data panels, config viewers, simple interactive tools |
 
 ## Iframe Panels
 
@@ -71,7 +72,7 @@ interface DockEntry {
   /** Icon URL, data URI, or Iconify icon name (e.g., 'ph:house-duotone') */
   icon: string
   /** Entry type */
-  type: 'iframe' | 'action' | 'custom-render' | 'launcher'
+  type: 'iframe' | 'action' | 'custom-render' | 'launcher' | 'json-render'
   /** URL to load in the iframe (for type: 'iframe') */
   url?: string
   /** Action configuration (for type: 'action') */
@@ -86,6 +87,10 @@ interface DockEntry {
     buttonStart?: string
     buttonLoading?: string
   }
+  /** Inline JSON spec (for type: 'json-render') */
+  spec?: JsonRenderSpec
+  /** Shared state key holding the JSON spec (for type: 'json-render') */
+  sharedStateKey?: string
 }
 ```
 
@@ -296,6 +301,163 @@ ctx.docks.register({
 > [!NOTE]
 > Built-in logs panel (`~logs`) is currently reserved and hidden while log UI is under development.
 
+## JSON Render Panels
+
+JSON render panels let you describe your UI as a JSON spec on the server side. The DevTools client renders it with built-in components powered by [json-render](https://github.com/vercel-labs/json-render). **No client code needed.**
+
+This is the simplest way to add a DevTools panel — you only write server-side TypeScript.
+
+### Basic Example
+
+```ts
+import { defineJsonRenderSpec } from '@vitejs/devtools-kit'
+
+ctx.docks.register({
+  id: 'my-panel',
+  title: 'My Panel',
+  icon: 'ph:chart-bar-duotone',
+  type: 'json-render',
+  spec: defineJsonRenderSpec({
+    root: 'root',
+    elements: {
+      root: {
+        type: 'Stack',
+        props: { direction: 'vertical', gap: 12 },
+        children: ['heading', 'info'],
+      },
+      heading: {
+        type: 'Text',
+        props: { content: 'Hello from JSON!', variant: 'heading' },
+      },
+      info: {
+        type: 'KeyValueTable',
+        props: {
+          entries: [
+            { key: 'Version', value: '1.0.0' },
+            { key: 'Status', value: 'Running' },
+          ],
+        },
+      },
+    },
+  }),
+})
+```
+
+### Dynamic Data with Shared State
+
+For dynamic UIs that update over time, store the spec in a [shared state](./shared-state) key:
+
+```ts
+ctx.docks.register({
+  id: 'my-panel',
+  title: 'My Panel',
+  icon: 'ph:chart-bar-duotone',
+  type: 'json-render',
+  sharedStateKey: 'my-plugin:ui',
+})
+
+const ui = await ctx.rpc.sharedState.get('my-plugin:ui', {
+  initialValue: defineJsonRenderSpec({ /* spec */ }),
+})
+
+// Later, update the UI reactively:
+ui.mutate((draft) => {
+  draft.elements.heading.props.content = 'Updated!'
+})
+```
+
+### Handling Actions via RPC
+
+Buttons in the spec can trigger RPC functions on the server:
+
+```ts
+// In the spec:
+defineJsonRenderSpec({
+  // ...
+  elements: {
+    'refresh-btn': {
+      type: 'Button',
+      props: { label: 'Refresh' },
+      on: { press: { action: 'my-plugin:refresh' } },
+    },
+  },
+})
+```
+
+```ts
+// On the server:
+ctx.rpc.register(defineRpcFunction({
+  name: 'my-plugin:refresh',
+  type: 'event',
+  setup: ctx => ({
+    handler: async () => {
+      // Fetch new data, then update the spec
+      ui.mutate((draft) => { /* ... */ })
+    },
+  }),
+}))
+```
+
+### Text Input with Two-Way Binding
+
+Use `$bindState` for two-way binding on text inputs, and `$state` to read the bound value in action params:
+
+```ts
+defineJsonRenderSpec({
+  // ...
+  elements: {
+    'my-input': {
+      type: 'TextInput',
+      props: {
+        placeholder: 'Type here...',
+        value: { $bindState: '/inputValue' },
+      },
+    },
+    'submit-btn': {
+      type: 'Button',
+      props: { label: 'Submit' },
+      on: {
+        press: {
+          action: 'my-plugin:submit',
+          params: { text: { $state: '/inputValue' } },
+        },
+      },
+    },
+  }
+})
+```
+
+The initial state can be set in the spec:
+
+```ts
+defineJsonRenderSpec({
+  root: 'root',
+  state: { inputValue: '' },
+  elements: { /* ... */ },
+})
+```
+
+### Available Components
+
+| Component | Description |
+|-----------|-------------|
+| `Stack` | Flex layout container (vertical/horizontal) |
+| `Card` | Container with optional title, collapsible |
+| `Text` | Text display (heading, body, caption, code variants) |
+| `Badge` | Status label (info, success, warning, error) |
+| `Button` | Clickable button — emits `press` event for actions |
+| `Icon` | Iconify icon by name |
+| `Divider` | Visual separator with optional label |
+| `TextInput` | Text input with `$bindState` two-way binding |
+| `KeyValueTable` | Key-value pairs display |
+| `DataTable` | Tabular data with columns and rows |
+| `CodeBlock` | Code display with optional filename |
+| `Progress` | Progress bar with label |
+| `Tree` | Expandable tree view for nested objects |
+
+> [!TIP]
+> See the [Git UI example](/kit/examples#git-ui) for a complete interactive plugin using json-render with RPC actions, text input, and dynamic state.
+
 ## Communication with Server
 
 All client scripts (actions and custom renderers) can communicate with the server using [RPC](./rpc):

docs/kit/examples.md

@@ -32,3 +32,18 @@ A file explorer dock that lists, reads, and writes files through RPC.
 - Detecting backend mode (`websocket` vs `static`) on the client
 
 **Source:** [`examples/plugin-file-explorer`](https://github.com/vitejs/devtools/tree/main/examples/plugin-file-explorer)
+
+## Git UI
+
+An interactive Git panel built entirely with server-side JSON specs — no client code at all.
+
+**Features demonstrated:**
+
+- Using the `json-render` dock type for zero-client-code panels
+- Building a `JsonRenderSpec` from server-side data (git branch, status, log)
+- Dynamic spec updates via shared state (`sharedStateKey`)
+- Button actions bridged to RPC functions (`git-ui:refresh`, `git-ui:commit`)
+- Text input with `$bindState` two-way binding and `$state` in action params
+- Updating dock badge text reactively
+
+**Source:** [`examples/plugin-git-ui`](https://github.com/vitejs/devtools/tree/main/examples/plugin-git-ui)

examples/plugin-git-ui/README.md

@@ -0,0 +1,54 @@
+# Example: DevTools Kit Git UI Plugin
+
+This example shows how to build a fully interactive DevTools panel using `@vitejs/devtools-kit`'s **json-render** dock type — with zero client-side code.
+
+It registers a `json-render` dock that displays the current git state: branch, staged/unstaged files, recent commits, and a commit form.
+
+## How It Works
+
+The entire UI is described as a JSON spec on the server side. The DevTools client renders it using built-in components powered by [@json-render/vue](https://github.com/vercel-labs/json-render).
+
+1. Node plugin (`src/node/plugin.ts`)
+   - collects git state by running `git` commands (`git branch`, `git log`, `git status`)
+   - builds a `JsonRenderSpec` describing the UI layout (Stack, Card, DataTable, TextInput, Button, etc.)
+   - stores the spec in a shared state key and registers a `json-render` dock entry
+   - registers two RPC functions:
+     - `git-ui:refresh` — re-reads git state and updates the spec
+     - `git-ui:commit` — runs `git commit -m "..."` with the message from the text input
+
+2. Client rendering (automatic)
+   - `ViewJsonRender.vue` subscribes to the shared state key
+   - renders the spec using the built-in devtools component registry
+   - bridges button clicks → RPC calls via the json-render action system
+   - text input uses `$bindState` for two-way binding; the commit action reads the message via `$state`
+
+**Key point**: there is no client-side code in this plugin. No Vue components, no Nuxt app, no iframe. The plugin only writes TypeScript on the server side.
+
+## Run The Example
+
+From the `examples/plugin-git-ui` directory (`cd examples/plugin-git-ui`):
+
+```bash
+pnpm play:dev
+```
+
+Then open the app URL, open Vite DevTools, and click the **Git** dock entry.
+
+You can also test it from the core playground:
+
+```bash
+pnpm -C packages/core run play
+```
+
+## Components Used
+
+| Component | Purpose in this example |
+|-----------|------------------------|
+| `Stack` | Layout — vertical/horizontal flex containers |
+| `Card` | Collapsible sections for staged, unstaged, and commits |
+| `Text` | Headings, branch name, empty state messages |
+| `Badge` | Change count indicator (warning/success) |
+| `Button` | Refresh and Commit actions |
+| `TextInput` | Commit message input with `$bindState` binding |
+| `DataTable` | Staged files, unstaged files, and commit history |
+| `Divider` | Visual separator |

examples/plugin-git-ui/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "example-plugin-git-ui",
+  "type": "module",
+  "version": "0.1.0",
+  "private": true,
+  "exports": {
+    ".": "./src/node/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "play:dev": "cd playground && DEBUG='vite:devtools:*' vite"
+  },
+  "peerDependencies": {
+    "vite": "*"
+  },
+  "dependencies": {
+    "@vitejs/devtools": "workspace:*",
+    "@vitejs/devtools-kit": "workspace:*"
+  },
+  "devDependencies": {
+    "vite": "catalog:build"
+  }
+}

examples/plugin-git-ui/playground/index.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Git UI Playground</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <style>
+      @media (prefers-color-scheme: dark) {
+        body {
+          color-scheme: dark;
+          background-color: #111;
+          color: #fff;
+        }
+      }
+    </style>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

examples/plugin-git-ui/playground/src/main.ts

@@ -0,0 +1,9 @@
+document.getElementById('app')!.innerHTML = `
+  <div style="padding: 2rem; font-family: system-ui, sans-serif;">
+    <h1>Git UI Plugin Playground</h1>
+    <p>Open Vite DevTools and click the <strong>Git</strong> dock entry to see the Git UI panel.</p>
+    <p style="opacity: 0.6; font-size: 14px;">
+      The panel shows your current branch, staged/unstaged files, recent commits, and lets you create commits — all rendered from a JSON spec with zero client-side code.
+    </p>
+  </div>
+`

examples/plugin-git-ui/playground/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

examples/plugin-git-ui/playground/vite.config.ts

@@ -0,0 +1,12 @@
+import { DevTools } from '@vitejs/devtools'
+import { defineConfig } from 'vite'
+import { GitUIPlugin } from '../src/node'
+
+export default defineConfig({
+  plugins: [
+    DevTools({
+      builtinDevTools: false,
+    }),
+    GitUIPlugin(),
+  ],
+})

examples/plugin-git-ui/src/node/index.ts

@@ -0,0 +1 @@
+export { GitUIPlugin } from './plugin'