feat: logs api

Author: antfu

docs/kit/logs.md

@@ -25,48 +25,41 @@ The Logs system allows plugins to emit structured log entries from both the serv
 | `labels` | `string[]` | No | Tags for filtering |
 | `autoDismiss` | `number` | No | Time in ms to auto-dismiss the toast (default: 5000) |
 | `autoDelete` | `number` | No | Time in ms to auto-delete the log entry |
+| `status` | `'loading' \| 'idle'` | No | Status indicator (shows spinner when `'loading'`) |
+| `id` | `string` | No | Explicit id for deduplication — re-adding with the same id updates the existing entry |
 
 ## Server-Side Usage
 
-In your plugin's `devtools.setup`, use `context.logs` to emit log entries:
+In your plugin's `devtools.setup`, use `context.logs` to emit log entries. The `add()` method returns a **handle** with `.update()` and `.dismiss()` helpers:
 
 ```ts
 export function myPlugin() {
   return {
     name: 'my-plugin',
     devtools: {
-      setup(context) {
+      async setup(context) {
         // Simple log
-        context.logs.add({
+        await context.logs.add({
           message: 'Plugin initialized',
           level: 'info',
         })
 
-        // Warning with file position
-        context.logs.add({
-          message: 'Deprecated API usage detected',
-          level: 'warn',
-          description: 'The `foo()` API is deprecated. Use `bar()` instead.',
-          filePosition: { file: 'src/app.ts', line: 42, column: 5 },
-          category: 'lint',
-        })
-
-        // Error with stack trace
-        context.logs.add({
-          message: 'Build failed',
-          level: 'error',
-          stacktrace: error.stack,
-          category: 'build',
+        // Log with loading state, then update
+        const log = await context.logs.add({
+          message: 'Building...',
+          level: 'info',
+          status: 'loading',
         })
 
-        // Short notification
-        context.logs.add({
-          message: 'Configuration reloaded',
+        // Later, update via the handle
+        await log.update({
+          message: 'Build complete',
           level: 'success',
-          notify: true,
-          autoDismiss: 3000,
-          autoDelete: 10000,
+          status: 'idle',
         })
+
+        // Or dismiss it
+        await log.dismiss()
       },
     },
   }
@@ -77,27 +70,54 @@ The `source` field is automatically set to the plugin name.
 
 ## Client-Side Usage
 
-From client-side code (running in the user's browser), emit logs via the RPC client:
+In dock action scripts, use `context.logs` — the same API as on the server:
 
 ```ts
-import { getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
+import type { DockClientScriptContext } from '@vitejs/devtools-kit/client'
+
+export default async function (context: DockClientScriptContext) {
+  const log1 = await context.logs.add({
+    message: 'Running audit...',
+    level: 'info',
+    status: 'loading',
+    notify: true,
+    category: 'a11y',
+  })
+
+  // ... do work ...
+
+  await log1.update({
+    message: 'Audit complete — 3 issues found',
+    level: 'warn',
+    status: 'idle',
+  })
+}
+```
 
-const client = await getDevToolsRpcClient()
+The `source` is automatically set to the dock entry id.
 
-await client.call('devtoolskit:internal:logs:add', {
-  message: 'Accessibility issue: missing alt text',
-  level: 'warn',
-  description: 'Images should have alt attributes for screen readers.',
-  elementPosition: {
-    selector: 'img.hero-image',
-    description: 'Hero image in the header',
-  },
-  category: 'a11y',
-  labels: ['wcag-2.1', 'images'],
-}, 'axe-plugin')
-```
+## Log Handle
+
+`context.logs.add()` returns a `DevToolsLogHandle` with:
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `handle.id` | The log entry id |
+| `handle.entry` | The current `DevToolsLogEntry` data |
+| `handle.update(patch)` | Partially update the log entry |
+| `handle.dismiss()` | Remove the log entry |
+
+## Deduplication
 
-The second argument to `logs:add` is the `source` identifier.
+When you call `context.logs.add()` with an explicit `id` that already exists, the existing entry is **updated** instead of duplicated. This is useful for logs that represent ongoing operations:
+
+```ts
+// First call creates the entry
+await context.logs.add({ id: 'my-scan', message: 'Scanning...', level: 'info', status: 'loading' })
+
+// Second call with same id updates it
+await context.logs.add({ id: 'my-scan', message: 'Scan complete', level: 'success', status: 'idle' })
+```
 
 ## Autofix
 
@@ -118,7 +138,7 @@ context.rpc.register(defineRpcFunction({
   }),
 }))
 
-context.logs.add({
+await context.logs.add({
   message: 'Deprecated API usage',
   level: 'warn',
   autofix: { type: 'rpc', name: 'my-plugin:fix-deprecated-api' },
@@ -130,7 +150,7 @@ context.logs.add({
 For server-side plugins, you can pass a function directly:
 
 ```ts
-context.logs.add({
+await context.logs.add({
   message: 'Missing configuration',
   level: 'warn',
   autofix: async () => {
@@ -144,7 +164,7 @@ context.logs.add({
 Set `notify: true` to show the log entry as a toast notification overlay. Toasts appear regardless of whether the Logs panel is open.
 
 ```ts
-context.logs.add({
+await context.logs.add({
   message: 'URL copied to clipboard',
   level: 'success',
   notify: true,
@@ -157,11 +177,11 @@ The default auto-dismiss time for toasts is 5 seconds.
 ## Managing Logs
 
 ```ts
-// Remove a specific log
-context.logs.remove(entry.id)
+// Remove a specific log by id
+await context.logs.remove(entryId)
 
 // Clear all logs
-context.logs.clear()
+await context.logs.clear()
 ```
 
 Logs have a maximum capacity of 1000 entries. When the limit is reached, the oldest entries are automatically removed.

examples/plugin-a11y-checker/src/client/run-axe.ts

@@ -2,7 +2,6 @@ import type { DevToolsLogLevel } from '@vitejs/devtools-kit'
 import type { DockClientScriptContext } from '@vitejs/devtools-kit/client'
 import axe from 'axe-core'
 
-const SOURCE = 'a11y-checker'
 const SUMMARY_LOG_ID = 'a11y-checker-summary'
 
 function impactToLevel(impact: string | undefined | null): DevToolsLogLevel {
@@ -19,17 +18,17 @@ function impactToLevel(impact: string | undefined | null): DevToolsLogLevel {
 }
 
 export default async function runA11yCheck(context: DockClientScriptContext): Promise<void> {
-  const { rpc } = context
+  const { logs } = context
 
   // Show loading state
-  await rpc.call('devtoolskit:internal:logs:add', {
+  const summary = await logs.add({
     id: SUMMARY_LOG_ID,
     message: 'Running accessibility audit...',
-    level: 'info' as DevToolsLogLevel,
+    level: 'info',
     category: 'a11y',
     status: 'loading',
     notify: true,
-  }, SOURCE)
+  })
 
   try {
     const results = await axe.run(document)
@@ -38,7 +37,7 @@ export default async function runA11yCheck(context: DockClientScriptContext): Pr
       const level = impactToLevel(violation.impact)
       const firstNode = violation.nodes[0]
 
-      await rpc.call('devtoolskit:internal:logs:add', {
+      await logs.add({
         id: `a11y-violation-${violation.id}`,
         message: violation.description,
         level,
@@ -51,35 +50,31 @@ export default async function runA11yCheck(context: DockClientScriptContext): Pr
               description: firstNode.html,
             }
           : undefined,
-      }, SOURCE)
+      })
     }
 
     const violationCount = results.violations.length
     const passCount = results.passes.length
 
-    // Update the summary log (dedup by id)
-    await rpc.call('devtoolskit:internal:logs:add', {
-      id: SUMMARY_LOG_ID,
+    // Update the summary log via handle
+    await summary.update({
       message: violationCount > 0
         ? `Found ${violationCount} violation${violationCount > 1 ? 's' : ''}, ${passCount} passed`
         : `All ${passCount} checks passed`,
-      level: (violationCount > 0 ? 'warn' : 'success') as DevToolsLogLevel,
-      category: 'a11y',
+      level: violationCount > 0 ? 'warn' : 'success',
       status: 'idle',
       notify: true,
       autoDismiss: 4000,
-    }, SOURCE)
+    })
   }
   catch (err) {
-    // Update the summary log with error
-    await rpc.call('devtoolskit:internal:logs:add', {
-      id: SUMMARY_LOG_ID,
+    // Update the summary log with error via handle
+    await summary.update({
       message: 'A11y audit failed',
-      level: 'error' as DevToolsLogLevel,
+      level: 'error',
       description: String(err),
-      category: 'a11y',
       status: 'idle',
       notify: true,
-    }, SOURCE)
+    })
   }
 }

packages/core/src/client/webcomponents/state/context.ts

@@ -7,6 +7,7 @@ import { computed, markRaw, reactive, ref, toRefs, watchEffect } from 'vue'
 import { BUILTIN_ENTRIES } from '../constants'
 import { docksGroupByCategories } from './dock-settings'
 import { createDockEntryState, DEFAULT_DOCK_PANEL_STORE, sharedStateToRef, useDocksEntries } from './docks'
+import { createClientLogsClient } from './logs-client'
 import { registerMainFrameDockActionHandler, requestDockPopupOpen, triggerMainFrameDockAction } from './popup'
 import { executeSetupScript } from './setup-script'
 
@@ -80,6 +81,7 @@ export async function createDocksContext(
       const scriptContext: DockClientScriptContext = reactive({
         ...toRefs(docksContext) as any,
         current,
+        logs: createClientLogsClient(rpc, entry.id),
       })
       await executeSetupScript(entry, scriptContext)
     }

packages/core/src/client/webcomponents/state/logs-client.ts

@@ -0,0 +1,34 @@
+import type { DevToolsLogEntry, DevToolsLogEntryInput, DevToolsLogHandle, DevToolsLogsClient } from '@vitejs/devtools-kit'
+import type { DevToolsRpcClient } from '@vitejs/devtools-kit/client'
+
+function createRpcHandle(rpc: DevToolsRpcClient, initialEntry: DevToolsLogEntry): DevToolsLogHandle {
+  let entry = initialEntry
+  return {
+    get entry() { return entry },
+    get id() { return entry.id },
+    async update(patch: Partial<DevToolsLogEntryInput>) {
+      const updated = await rpc.call('devtoolskit:internal:logs:update', entry.id, patch)
+      if (updated)
+        entry = updated
+      return updated ?? undefined
+    },
+    async dismiss() {
+      await rpc.call('devtoolskit:internal:logs:remove', entry.id)
+    },
+  }
+}
+
+export function createClientLogsClient(rpc: DevToolsRpcClient, source: string): DevToolsLogsClient {
+  return {
+    async add(input: DevToolsLogEntryInput): Promise<DevToolsLogHandle> {
+      const entry = await rpc.call('devtoolskit:internal:logs:add', input, source)
+      return createRpcHandle(rpc, entry)
+    },
+    async remove(id: string): Promise<void> {
+      await rpc.call('devtoolskit:internal:logs:remove', id)
+    },
+    async clear(): Promise<void> {
+      await rpc.call('devtoolskit:internal:logs:clear')
+    },
+  }
+}

packages/kit/src/client/client-script.ts

@@ -1,3 +1,4 @@
+import type { DevToolsLogsClient } from '../types/logs'
 import type { DockEntryState, DocksContext } from './docks'
 
 /**
@@ -8,4 +9,8 @@ export interface DockClientScriptContext extends DocksContext {
    * The state of the current dock entry
    */
   current: DockEntryState
+  /**
+   * Logs client scoped to this dock entry's source
+   */
+  logs: DevToolsLogsClient
 }

packages/kit/src/types/logs.ts

@@ -106,6 +106,26 @@ export type DevToolsLogEntryInput = Omit<DevToolsLogEntry, 'id' | 'timestamp' |
   timestamp?: number
 }
 
+export interface DevToolsLogHandle {
+  /** The underlying log entry data */
+  readonly entry: DevToolsLogEntry
+  /** Shortcut to entry.id */
+  readonly id: string
+  /** Partial update of this log entry */
+  update: (patch: Partial<DevToolsLogEntryInput>) => Promise<DevToolsLogEntry | undefined>
+  /** Remove this log entry */
+  dismiss: () => Promise<void>
+}
+
+export interface DevToolsLogsClient {
+  /** Add a log entry, returns a handle for subsequent updates/dismissal */
+  add: (input: DevToolsLogEntryInput) => Promise<DevToolsLogHandle>
+  /** Remove a log entry by id */
+  remove: (id: string) => Promise<void>
+  /** Clear all log entries */
+  clear: () => Promise<void>
+}
+
 export interface DevToolsLogsHost {
   readonly entries: Map<string, DevToolsLogEntry>
   readonly events: EventEmitter<{

packages/kit/src/types/vite-plugin.ts

@@ -63,7 +63,7 @@ export interface DevToolsNodeContext {
    */
   terminals: DevToolsTerminalHost
   /**
-   * Logs host, for emitting structured log entries
+   * Logs host, for emitting and managing structured log entries
    */
   logs: DevToolsLogsHost
 }