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

package/skills/vite-devtools-kit/references/shared-state-patterns.md

@@ -0,0 +1,292 @@
+# Shared State Patterns
+
+Synchronized state between server and all clients.
+
+## Basic Usage
+
+Shared state is available during `devtools.setup()` — you can initialize it directly in the setup hook.
+
+### Server-Side
+
+```ts
+const state = await ctx.rpc.sharedState.get('my-plugin:state', {
+  initialValue: {
+    count: 0,
+    items: [],
+    settings: { theme: 'dark' },
+  },
+})
+
+// Read
+const current = state.value()
+
+// Mutate (syncs to all clients)
+state.mutate((draft) => {
+  draft.count += 1
+  draft.items.push({ id: Date.now(), name: 'New' })
+})
+```
+
+### Client-Side
+
+```ts
+import { getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
+
+const client = await getDevToolsRpcClient()
+const state = await client.rpc.sharedState.get('my-plugin:state')
+
+// Read
+console.log(state.value())
+
+// Subscribe
+state.on('updated', (newState) => {
+  console.log('Updated:', newState)
+})
+```
+
+## Type-Safe Shared State
+
+```ts
+// src/types.ts
+interface MyPluginState {
+  count: number
+  items: Array<{ id: string, name: string }>
+  settings: {
+    theme: 'light' | 'dark'
+    notifications: boolean
+  }
+}
+
+declare module '@vitejs/devtools-kit' {
+  interface DevToolsRpcSharedStates {
+    'my-plugin:state': MyPluginState
+  }
+}
+```
+
+## Vue Integration
+
+```ts
+// composables/useSharedState.ts
+import { getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
+import { onMounted, shallowRef } from 'vue'
+
+export function useSharedState<T>(name: string) {
+  const state = shallowRef<T | null>(null)
+  const loading = shallowRef(true)
+
+  onMounted(async () => {
+    const client = await getDevToolsRpcClient()
+    const shared = await client.rpc.sharedState.get<T>(name)
+
+    state.value = shared.value()
+    loading.value = false
+
+    shared.on('updated', (newState) => {
+      state.value = newState
+    })
+  })
+
+  return { state, loading }
+}
+
+// Usage in component
+const { state, loading } = useSharedState<MyPluginState>('my-plugin:state')
+```
+
+### Full Vue Component Example
+
+```vue
+<script setup lang="ts">
+import { getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
+import { onMounted, shallowRef } from 'vue'
+
+interface PluginState {
+  count: number
+  items: string[]
+}
+
+const state = shallowRef<PluginState | null>(null)
+
+onMounted(async () => {
+  const client = await getDevToolsRpcClient()
+  const shared = await client.rpc.sharedState.get<PluginState>('my-plugin:state')
+
+  state.value = shared.value()
+
+  shared.on('updated', (newState) => {
+    state.value = newState
+  })
+})
+</script>
+
+<template>
+  <div v-if="state">
+    <p>Count: {{ state.count }}</p>
+    <ul>
+      <li v-for="item in state.items" :key="item">
+        {{ item }}
+      </li>
+    </ul>
+  </div>
+</template>
+```
+
+## React Integration
+
+```tsx
+import { getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
+import { useEffect, useState } from 'react'
+
+function useSharedState<T>(name: string, fallback: T) {
+  const [state, setState] = useState<T>(fallback)
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    let mounted = true
+
+    async function init() {
+      const client = await getDevToolsRpcClient()
+      const shared = await client.rpc.sharedState.get<T>(name)
+
+      if (mounted) {
+        setState(shared.value() ?? fallback)
+        setLoading(false)
+
+        shared.on('updated', (newState) => {
+          if (mounted)
+            setState(newState)
+        })
+      }
+    }
+
+    init()
+    return () => {
+      mounted = false
+    }
+  }, [name])
+
+  return { state, loading }
+}
+
+// Usage
+function MyComponent() {
+  const { state, loading } = useSharedState('my-plugin:state', { count: 0 })
+
+  if (loading)
+    return <div>Loading...</div>
+
+  return (
+    <div>
+      Count:
+      {state.count}
+    </div>
+  )
+}
+```
+
+## Svelte Integration
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte'
+  import { writable } from 'svelte/store'
+  import { getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
+
+  interface PluginState {
+    count: number
+  }
+
+  const state = writable<PluginState>({ count: 0 })
+
+  onMount(async () => {
+    const client = await getDevToolsRpcClient()
+    const shared = await client.rpc.sharedState.get<PluginState>('my-plugin:state')
+
+    state.set(shared.value())
+
+    shared.on('updated', (newState) => {
+      state.set(newState)
+    })
+  })
+</script>
+
+<p>Count: {$state.count}</p>
+```
+
+## Best Practices
+
+### Batch Mutations
+
+```ts
+// Good - single sync event
+state.mutate((draft) => {
+  draft.count += 1
+  draft.lastUpdate = Date.now()
+  draft.items.push(newItem)
+})
+
+// Bad - multiple sync events
+state.mutate((d) => {
+  d.count += 1
+})
+state.mutate((d) => {
+  d.lastUpdate = Date.now()
+})
+state.mutate((d) => {
+  d.items.push(newItem)
+})
+```
+
+### Keep State Small
+
+For large datasets, store IDs in shared state and fetch details via RPC:
+
+<!-- eslint-skip -->
+```ts
+// Shared state (small)
+{
+  moduleIds: ['a', 'b', 'c'],
+  selectedId: 'a'
+}
+
+// Fetch full data via RPC when needed
+const module = await rpc.call('my-plugin:get-module', state.selectedId)
+```
+
+### Serializable Data Only
+
+<!-- eslint-skip -->
+```ts
+// Bad - functions can't be serialized
+{ count: 0, increment: () => {} }
+
+// Bad - circular references
+const obj = { child: null }
+obj.child = obj
+
+// Good - plain data
+{ count: 0, items: [{ id: 1 }] }
+```
+
+### Real-Time Updates Example
+
+```ts
+const plugin: Plugin = {
+  devtools: {
+    async setup(ctx) {
+      const state = await ctx.rpc.sharedState.get('my-plugin:state', {
+        initialValue: { modules: [], lastUpdate: 0 },
+      })
+
+      // Update state when Vite processes modules
+      ctx.viteServer?.watcher.on('change', (file) => {
+        state.mutate((draft) => {
+          draft.modules.push(file)
+          draft.lastUpdate = Date.now()
+        })
+      })
+    }
+  }
+}
+```

package/dist/index-BtaHil_c.d.ts

@@ -1,156 +0,0 @@
-import { BirpcFn, BirpcReturn as BirpcReturn$1 } from "birpc";
-import { Plugin, ResolvedConfig, ViteDevServer } from "vite";
-
-//#region src/types/rpc-augments.d.ts
-/**
- * To be extended
- */
-interface DevToolsRpcClientFunctions {}
-/**
- * To be extended
- */
-interface DevToolsRpcServerFunctions {}
-//#endregion
-//#region src/types/utils.d.ts
-type Thenable<T> = T | Promise<T>;
-type EntriesToObject<T extends readonly [string, any][]> = { [K in T[number] as K[0]]: K[1] };
-//#endregion
-//#region src/types/views.d.ts
-interface DevToolsDockHost {
-  views: Map<string, DevToolsDockEntry>;
-  register: (entry: DevToolsDockEntry) => void;
-  update: (entry: DevToolsDockEntry) => void;
-  values: () => DevToolsDockEntry[];
-}
-interface DevToolsViewHost {
-  /**
-   * @internal
-   */
-  buildStaticDirs: {
-    baseUrl: string;
-    distDir: string;
-  }[];
-  /**
-   * Helper to host static files
-   * - In `dev` mode, it will register middleware to `viteServer.middlewares` to host the static files
-   * - In `build` mode, it will copy the static files to the dist directory
-   */
-  hostStatic: (baseUrl: string, distDir: string) => void;
-}
-interface DevToolsDockEntryBase {
-  id: string;
-  title: string;
-  icon: string;
-}
-interface ClientScriptEntry {
-  /**
-   * The filepath or module name to import from
-   */
-  importFrom: string;
-  /**
-   * The name to import the module as
-   *
-   * @default 'default'
-   */
-  importName?: string;
-}
-interface DevToolsViewIframe extends DevToolsDockEntryBase {
-  type: 'iframe';
-  url: string;
-  /**
-   * The id of the iframe, if multiple tabs is assigned with the same id, the iframe will be shared.
-   *
-   * When not provided, it would be treated as a unique frame.
-   */
-  frameId?: string;
-  /**
-   * Optional script to import into the iframe
-   */
-  import?: ClientScriptEntry;
-}
-interface DevToolsViewWebComponent extends DevToolsDockEntryBase {
-  type: 'webcomponent';
-  import: ClientScriptEntry;
-}
-interface DevToolsViewAction extends DevToolsDockEntryBase {
-  type: 'action';
-  import: ClientScriptEntry;
-}
-interface DevToolsViewCustomRender extends DevToolsDockEntryBase {
-  type: 'custom-render';
-  import: ClientScriptEntry;
-}
-type DevToolsDockEntry = DevToolsViewIframe | DevToolsViewWebComponent | DevToolsViewAction | DevToolsViewCustomRender;
-//#endregion
-//#region src/types/vite-plugin.d.ts
-interface DevToolsCapabilities {
-  rpc?: boolean;
-  views?: boolean;
-}
-interface DevToolsPluginOptions {
-  capabilities?: {
-    dev?: DevToolsCapabilities | boolean;
-    build?: DevToolsCapabilities | boolean;
-  };
-  setup: (context: DevToolsNodeContext) => void | Promise<void>;
-}
-interface DevToolsNodeContext {
-  readonly cwd: string;
-  readonly mode: 'dev' | 'build';
-  readonly viteConfig: ResolvedConfig;
-  readonly viteServer?: ViteDevServer;
-  rpc: RpcFunctionsHost;
-  docks: DevToolsDockHost;
-  views: DevToolsViewHost;
-  utils: DevToolsNodeUtils;
-}
-interface DevToolsNodeUtils {
-  clientEntryFromSimpleFunction: (fn: () => void) => ClientScriptEntry;
-}
-interface ConnectionMeta {
-  backend: 'websocket' | 'static';
-  websocket?: number | string;
-}
-//#endregion
-//#region src/types/rpc.d.ts
-/**
- * Type of the RPC function,
- * - static: A function that returns a static data (can be cached and dumped)
- * - action: A function that performs an action (no data returned)
- * - query: A function that queries a resource
- */
-type RpcFunctionType = 'static' | 'action' | 'query';
-interface RpcFunctionsHost {
-  context: DevToolsNodeContext;
-  readonly functions: DevToolsRpcServerFunctions;
-  readonly definitions: Map<string, RpcFunctionDefinition<string, any, any, any>>;
-  register: (fn: RpcFunctionDefinition<string, any, any, any>) => void;
-  update: (fn: RpcFunctionDefinition<string, any, any, any>) => void;
-}
-interface RpcFunctionSetupResult<ARGS extends any[], RETURN = void> {
-  handler: (...args: ARGS) => RETURN;
-}
-interface RpcFunctionDefinition<NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[] = [], RETURN = void> {
-  name: NAME;
-  type: TYPE;
-  setup: (context: DevToolsNodeContext) => Thenable<RpcFunctionSetupResult<ARGS, RETURN>>;
-  handler?: (...args: ARGS) => RETURN;
-  __resolved?: RpcFunctionSetupResult<ARGS, RETURN>;
-  __promise?: Thenable<RpcFunctionSetupResult<ARGS, RETURN>>;
-}
-type RpcDefinitionsToFunctions<T extends readonly RpcFunctionDefinition<any, any, any>[]> = EntriesToObject<{ [K in keyof T]: [T[K]['name'], Awaited<ReturnType<T[K]['setup']>>['handler']] }>;
-type RpcDefinitionsFilter<T extends readonly RpcFunctionDefinition<any, any, any>[], Type extends RpcFunctionType> = { [K in keyof T]: T[K] extends {
-  type: Type;
-} ? T[K] : never };
-//#endregion
-//#region src/types/vite-augment.d.ts
-declare module 'vite' {
-  interface Plugin {
-    devtools?: DevToolsPluginOptions;
-  }
-}
-interface PluginWithDevTools extends Plugin {
-  devtools?: DevToolsPluginOptions;
-}
-//#endregion
-export { DevToolsViewWebComponent as C, DevToolsRpcServerFunctions as D, DevToolsRpcClientFunctions as E, DevToolsViewIframe as S, Thenable as T, DevToolsDockEntryBase as _, RpcDefinitionsToFunctions as a, DevToolsViewCustomRender as b, RpcFunctionType as c, DevToolsCapabilities as d, DevToolsNodeContext as f, DevToolsDockEntry as g, ClientScriptEntry as h, RpcDefinitionsFilter as i, RpcFunctionsHost as l, DevToolsPluginOptions as m, BirpcFn as n, RpcFunctionDefinition as o, DevToolsNodeUtils as p, BirpcReturn$1 as r, RpcFunctionSetupResult as s, PluginWithDevTools as t, ConnectionMeta as u, DevToolsDockHost as v, EntriesToObject as w, DevToolsViewHost as x, DevToolsViewAction as y };