@vitejs/devtools-kit 0.0.0-alpha.8 → 0.1.0

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

@@ -0,0 +1,256 @@
+# 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 References
+
+### In-Repo Examples
+
+Reference these for code structure and patterns when building new integrations:
+
+- [`examples/plugin-a11y-checker`](https://github.com/vitejs/devtools/tree/main/examples/plugin-a11y-checker) — Action entry, client-side audits, logs with element positions, log handle updates
+- [`examples/plugin-file-explorer`](https://github.com/vitejs/devtools/tree/main/examples/plugin-file-explorer) — Iframe entry, multiple RPC types, hosted UI panel, RPC dump for static builds
+
+### Internal Packages
+
+See [packages/vite](https://github.com/vitejs/devtools/tree/main/packages/vite) for a complete implementation 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 {}
+}
+```