@vitejs/devtools-kit 0.0.0-alpha.3 → 0.0.0-alpha.31

package/skills/vite-devtools-kit/references/dock-entry-types.md

@@ -0,0 +1,240 @@
+# Dock Entry Types
+
+Detailed configuration for each dock entry type.
+
+## Common Properties
+
+All dock entries share these properties:
+
+```ts
+interface DockEntryBase {
+  id: string // Unique identifier
+  title: string // Display title
+  icon: string // URL, data URI, or Iconify name
+  category?: string // Grouping category
+  defaultOrder?: number // Sort order (higher = earlier)
+  isHidden?: boolean // Hide from dock
+}
+```
+
+## Icons
+
+<!-- eslint-skip -->
+
+```ts
+// Iconify (recommended)
+icon: 'ph:chart-bar-duotone'  // Phosphor Icons
+icon: 'carbon:analytics'       // Carbon Icons
+icon: 'mdi:view-dashboard'     // Material Design
+
+// URL
+icon: 'https://example.com/logo.svg'
+
+// Data URI
+icon: 'data:image/svg+xml,<svg>...</svg>'
+
+// Light/dark variants
+icon: {
+  light: 'https://example.com/logo-light.svg',
+  dark: 'https://example.com/logo-dark.svg',
+}
+```
+
+Browse icons at [Iconify](https://icon-sets.iconify.design/).
+
+## Iframe Entries
+
+Most common type. Displays your UI in an isolated iframe.
+
+```ts
+interface IframeEntry extends DockEntryBase {
+  type: 'iframe'
+  url: string // URL to load
+  frameId?: string // Share iframe between entries
+  clientScript?: ClientScriptEntry // Optional client script
+}
+
+// Example
+ctx.docks.register({
+  id: 'my-plugin',
+  title: 'My Plugin',
+  icon: 'ph:house-duotone',
+  type: 'iframe',
+  url: '/.my-plugin/',
+})
+```
+
+### Hosting Your Own UI
+
+```ts
+import { fileURLToPath } from 'node:url'
+
+const clientDist = fileURLToPath(
+  new URL('../dist/client', import.meta.url)
+)
+
+ctx.views.hostStatic('/.my-plugin/', clientDist)
+
+ctx.docks.register({
+  id: 'my-plugin',
+  title: 'My Plugin',
+  icon: 'ph:house-duotone',
+  type: 'iframe',
+  url: '/.my-plugin/',
+})
+```
+
+## Action Entries
+
+Buttons that trigger client-side scripts. Perfect for inspectors and toggles.
+
+```ts
+interface ActionEntry extends DockEntryBase {
+  type: 'action'
+  action: {
+    importFrom: string // Package export path
+    importName?: string // Export name (default: 'default')
+  }
+}
+
+// Registration
+ctx.docks.register({
+  id: 'my-inspector',
+  title: 'Inspector',
+  icon: 'ph:cursor-duotone',
+  type: 'action',
+  action: {
+    importFrom: 'my-plugin/devtools-action',
+    importName: 'default',
+  },
+})
+```
+
+### Client Script Implementation
+
+```ts
+// src/devtools-action.ts
+import type { DevToolsClientScriptContext } from '@vitejs/devtools-kit/client'
+
+export default function setup(ctx: DevToolsClientScriptContext) {
+  let overlay: HTMLElement | null = null
+
+  ctx.current.events.on('entry:activated', () => {
+    overlay = document.createElement('div')
+    overlay.style.cssText = `
+      position: fixed;
+      inset: 0;
+      cursor: crosshair;
+      z-index: 99999;
+    `
+    overlay.onclick = (e) => {
+      const target = document.elementFromPoint(e.clientX, e.clientY)
+      console.log('Selected:', target)
+    }
+    document.body.appendChild(overlay)
+  })
+
+  ctx.current.events.on('entry:deactivated', () => {
+    overlay?.remove()
+    overlay = null
+  })
+}
+```
+
+### Package Export
+
+```json
+{
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./devtools-action": "./dist/devtools-action.mjs"
+  }
+}
+```
+
+## Custom Render Entries
+
+Render directly into the DevTools panel DOM. Use when you need direct DOM access or framework mounting.
+
+```ts
+interface CustomRenderEntry extends DockEntryBase {
+  type: 'custom-render'
+  renderer: {
+    importFrom: string
+    importName?: string
+  }
+}
+
+ctx.docks.register({
+  id: 'my-custom',
+  title: 'Custom View',
+  icon: 'ph:code-duotone',
+  type: 'custom-render',
+  renderer: {
+    importFrom: 'my-plugin/devtools-renderer',
+    importName: 'default',
+  },
+})
+```
+
+### Renderer Implementation
+
+```ts
+// src/devtools-renderer.ts
+import type { DevToolsClientScriptContext } from '@vitejs/devtools-kit/client'
+
+export default function setup(ctx: DevToolsClientScriptContext) {
+  ctx.current.events.on('dom:panel:mounted', (panel) => {
+    // Vanilla JS
+    panel.innerHTML = `<div style="padding: 16px;">Hello</div>`
+
+    // Or mount Vue
+    // import { createApp } from 'vue'
+    // import App from './App.vue'
+    // createApp(App).mount(panel)
+
+    // Or mount React
+    // import { createRoot } from 'react-dom/client'
+    // createRoot(panel).render(<App />)
+  })
+}
+```
+
+## Client Script Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `entry:activated` | - | Entry was selected |
+| `entry:deactivated` | - | Entry was deselected |
+| `entry:updated` | `DevToolsDockUserEntry` | Entry metadata changed |
+| `dom:panel:mounted` | `HTMLDivElement` | Panel DOM ready (custom-render only) |
+| `dom:iframe:mounted` | `HTMLIFrameElement` | Iframe mounted (iframe only) |
+
+## Category Order
+
+Default category ordering:
+
+```ts
+DEFAULT_CATEGORIES_ORDER = {
+  '~viteplus': -1000, // First
+  'default': 0,
+  'app': 100,
+  'framework': 200,
+  'web': 300,
+  'advanced': 400,
+  '~builtin': 1000, // Last
+}
+```
+
+Use `category` to group related entries:
+
+```ts
+ctx.docks.register({
+  id: 'my-plugin',
+  title: 'My Plugin',
+  icon: 'ph:house-duotone',
+  type: 'iframe',
+  url: '/.my-plugin/',
+  category: 'framework',
+})
+```

package/skills/vite-devtools-kit/references/project-structure.md

@@ -0,0 +1,247 @@
+# Project Structure
+
+Recommended file organization for DevTools integrations.
+
+## Basic Structure
+
+```
+my-devtools-plugin/
+├── src/
+│   ├── node/
+│   │   ├── index.ts          # Plugin entry (exports main plugin)
+│   │   ├── rpc/
+│   │   │   ├── index.ts      # RPC function exports
+│   │   │   └── functions/    # Individual RPC functions
+│   │   │       ├── get-modules.ts
+│   │   │       └── get-stats.ts
+│   │   └── utils.ts          # Server-side utilities
+│   ├── client/
+│   │   ├── main.ts           # Client app entry
+│   │   ├── App.vue           # Root component
+│   │   └── composables/
+│   │       └── rpc.ts        # RPC composables
+│   ├── types.ts              # Type augmentations
+│   └── shared/
+│       └── constants.ts      # Shared constants
+├── dist/
+│   ├── index.mjs             # Node plugin bundle
+│   └── client/               # Built client assets
+├── package.json
+└── tsconfig.json
+```
+
+## Package.json Configuration
+
+```json
+{
+  "name": "my-devtools-plugin",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./devtools-action": {
+      "import": "./dist/devtools-action.mjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsdown src/node/index.ts && vite build src/client",
+    "dev": "vite src/client"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@vitejs/devtools-kit": "^0.x.x",
+    "vite": "^6.x.x"
+  }
+}
+```
+
+## Plugin Entry (src/node/index.ts)
+
+```ts
+/// <reference types="@vitejs/devtools-kit" />
+import type { Plugin } from 'vite'
+import { fileURLToPath } from 'node:url'
+import { rpcFunctions } from './rpc'
+import '../types'
+
+const clientDist = fileURLToPath(
+  new URL('../../dist/client', import.meta.url)
+)
+
+export default function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',
+
+    devtools: {
+      setup(ctx) {
+        // Register all RPC functions
+        for (const fn of rpcFunctions) {
+          ctx.rpc.register(fn)
+        }
+
+        // Host static UI
+        ctx.views.hostStatic('/.my-plugin/', clientDist)
+
+        // Register dock entry
+        ctx.docks.register({
+          id: 'my-plugin',
+          title: 'My Plugin',
+          icon: 'ph:puzzle-piece-duotone',
+          type: 'iframe',
+          url: '/.my-plugin/',
+        })
+      },
+    },
+  }
+}
+```
+
+## RPC Index (src/node/rpc/index.ts)
+
+```ts
+import type { RpcDefinitionsToFunctions } from '@vitejs/devtools-kit'
+import { getModules } from './functions/get-modules'
+import { getStats } from './functions/get-stats'
+import '@vitejs/devtools-kit'
+
+export const rpcFunctions = [
+  getModules,
+  getStats,
+] as const
+
+export type ServerFunctions = RpcDefinitionsToFunctions<typeof rpcFunctions>
+
+declare module '@vitejs/devtools-kit' {
+  export interface DevToolsRpcServerFunctions extends ServerFunctions {}
+}
+```
+
+## RPC Function (src/node/rpc/functions/get-modules.ts)
+
+```ts
+import type { Module } from '../../../types'
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+export const getModules = defineRpcFunction({
+  name: 'my-plugin:get-modules',
+  type: 'query',
+  setup: (ctx) => {
+    return {
+      handler: async (): Promise<Module[]> => {
+        // Access vite config, server, etc. from ctx
+        const root = ctx.viteConfig.root
+        return []
+      },
+    }
+  },
+})
+```
+
+## Type Augmentations (src/types.ts)
+
+```ts
+import '@vitejs/devtools-kit'
+
+export interface Module {
+  id: string
+  size: number
+  imports: string[]
+}
+
+export interface MyPluginState {
+  modules: Module[]
+  selectedId: string | null
+}
+
+declare module '@vitejs/devtools-kit' {
+  interface DevToolsRpcSharedStates {
+    'my-plugin:state': MyPluginState
+  }
+}
+```
+
+## Client Entry (src/client/main.ts)
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App).mount('#app')
+```
+
+## Client RPC Composable (src/client/composables/rpc.ts)
+
+```ts
+import { getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
+
+let clientPromise: Promise<Awaited<ReturnType<typeof getDevToolsRpcClient>>>
+
+export function useRpc() {
+  if (!clientPromise) {
+    clientPromise = getDevToolsRpcClient()
+  }
+  return clientPromise
+}
+```
+
+## Client App Component (src/client/App.vue)
+
+```vue
+<script setup lang="ts">
+import type { Module } from '../types'
+import { onMounted, shallowRef } from 'vue'
+import { useRpc } from './composables/rpc'
+
+const modules = shallowRef<Module[]>([])
+const loading = shallowRef(true)
+
+onMounted(async () => {
+  const rpc = await useRpc()
+  modules.value = await rpc.call('my-plugin:get-modules')
+  loading.value = false
+})
+</script>
+
+<template>
+  <div class="p-4">
+    <h1 class="text-xl font-bold mb-4">
+      My Plugin
+    </h1>
+    <div v-if="loading">
+      Loading...
+    </div>
+    <ul v-else>
+      <li v-for="mod in modules" :key="mod.id">
+        {{ mod.id }} ({{ mod.size }} bytes)
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+## Vite Config for Client (src/client/vite.config.ts)
+
+```ts
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [vue()],
+  build: {
+    outDir: '../../dist/client',
+    emptyOutDir: true,
+  },
+})
+```
+
+## Real-World Reference
+
+See [packages/vite](https://github.com/user/vite-devtools/tree/main/packages/vite) for a complete implementation example with:
+
+- Multiple RPC functions organized by feature
+- Nuxt-based client UI
+- Complex data visualization
+- Build session management

package/skills/vite-devtools-kit/references/rpc-patterns.md

@@ -0,0 +1,185 @@
+# RPC Patterns
+
+Advanced patterns for server-client communication in DevTools integrations.
+
+## Function Types
+
+| Type | Caching | Use Case |
+|------|---------|----------|
+| `query` | Can be cached | Read operations, data fetching |
+| `action` | Never cached | Mutations, side effects |
+| `static` | Cached indefinitely | Constants, configuration |
+
+## Type-Safe RPC Setup
+
+### Step 1: Define Types
+
+```ts
+// src/types.ts
+import '@vitejs/devtools-kit'
+
+interface Module {
+  id: string
+  size: number
+  imports: string[]
+}
+
+declare module '@vitejs/devtools-kit' {
+  interface DevToolsRpcServerFunctions {
+    'my-plugin:list-modules': () => Promise<Module[]>
+    'my-plugin:get-module': (id: string) => Promise<Module | null>
+    'my-plugin:analyze': (options: { deep: boolean }) => Promise<void>
+  }
+
+  interface DevToolsRpcClientFunctions {
+    'my-plugin:highlight': (selector: string) => void
+    'my-plugin:refresh': () => void
+  }
+}
+```
+
+### Step 2: Import Types File
+
+```ts
+// src/node/plugin.ts
+import '../types' // Side-effect import for type augmentation
+```
+
+### Step 3: Register Functions
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+const listModules = defineRpcFunction({
+  name: 'my-plugin:list-modules',
+  type: 'query',
+  setup: () => ({
+    handler: async (): Promise<Module[]> => {
+      return Array.from(moduleMap.values())
+    },
+  }),
+})
+```
+
+## Context Access in Setup
+
+The `setup` function receives the full `DevToolsNodeContext`:
+
+```ts
+defineRpcFunction({
+  name: 'my-plugin:get-config',
+  type: 'static',
+  setup: (ctx) => {
+    // Access at setup time (runs once)
+    const root = ctx.viteConfig.root
+    const isDev = ctx.mode === 'dev'
+
+    return {
+      handler: async () => ({
+        root,
+        isDev,
+        plugins: ctx.viteConfig.plugins.map(p => p.name),
+      }),
+    }
+  },
+})
+```
+
+## Broadcasting Patterns
+
+### Basic Broadcast
+
+```ts
+// Notify all clients
+ctx.rpc.broadcast({
+  method: 'my-plugin:refresh',
+  args: [],
+})
+```
+
+### Broadcast with Data
+
+```ts
+ctx.viteServer?.watcher.on('change', (file) => {
+  ctx.rpc.broadcast({
+    method: 'my-plugin:file-changed',
+    args: [{ path: file, timestamp: Date.now() }],
+  })
+})
+```
+
+### Optional Broadcast
+
+```ts
+// Won't error if no clients have registered the function
+ctx.rpc.broadcast({
+  method: 'my-plugin:optional-update',
+  args: [data],
+  optional: true,
+})
+```
+
+## Client Function Registration
+
+```ts
+// Client-side (action/renderer script)
+export default function setup(ctx: DevToolsClientScriptContext) {
+  ctx.current.rpc.client.register({
+    name: 'my-plugin:highlight',
+    type: 'action',
+    handler: (selector: string) => {
+      const el = document.querySelector(selector)
+      if (el) {
+        el.style.outline = '3px solid red'
+        setTimeout(() => {
+          el.style.outline = ''
+        }, 2000)
+      }
+    },
+  })
+}
+```
+
+## Collecting RPC Functions
+
+Organize RPC functions in a registry pattern:
+
+```ts
+import { analyzeBundle } from './functions/analyze-bundle'
+// src/node/rpc/index.ts
+import { getModules } from './functions/get-modules'
+import { getStats } from './functions/get-stats'
+
+export const rpcFunctions = [
+  getModules,
+  getStats,
+  analyzeBundle,
+] as const
+
+// Register all in setup
+for (const fn of rpcFunctions) {
+  ctx.rpc.register(fn)
+}
+```
+
+## Type Extraction Utilities
+
+```ts
+import type {
+  RpcDefinitionsFilter,
+  RpcDefinitionsToFunctions,
+} from '@vitejs/devtools-kit'
+
+// Extract all function types
+export type ServerFunctions = RpcDefinitionsToFunctions<typeof rpcFunctions>
+
+// Extract only static functions
+export type StaticFunctions = RpcDefinitionsToFunctions<
+  RpcDefinitionsFilter<typeof rpcFunctions, 'static'>
+>
+
+// Augment the global interface
+declare module '@vitejs/devtools-kit' {
+  export interface DevToolsRpcServerFunctions extends ServerFunctions {}
+}
+```