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

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

@@ -0,0 +1,290 @@
+# Shared State Patterns
+
+Synchronized state between server and all clients.
+
+## Basic Usage
+
+### 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/client.d.ts

@@ -1,17 +0,0 @@
-import { ConnectionMeta, DevToolsRpcClientFunctions, DevToolsRpcServerFunctions } from "./rpc-ls6mUIa2.js";
-import { WebSocketRpcClientOptions } from "@vitejs/devtools-rpc/presets/ws/client";
-import { BirpcOptions, BirpcReturn } from "birpc";
-
-//#region src/client/index.d.ts
-interface DevToolsRpcClientOptions {
-  connectionMeta?: ConnectionMeta;
-  baseURL?: string[];
-  wsOptions?: Partial<WebSocketRpcClientOptions>;
-  rpcOptions?: Partial<BirpcOptions<DevToolsRpcServerFunctions>>;
-}
-declare function getDevToolsRpcClient(options?: DevToolsRpcClientOptions): Promise<{
-  connectionMeta: ConnectionMeta;
-  rpc: BirpcReturn<DevToolsRpcServerFunctions, DevToolsRpcClientFunctions>;
-}>;
-//#endregion
-export { DevToolsRpcClientOptions, getDevToolsRpcClient };

package/dist/client.js

@@ -1,38 +0,0 @@
-import { createRpcClient } from "@vitejs/devtools-rpc";
-import { createWsRpcPreset } from "@vitejs/devtools-rpc/presets/ws/client";
-
-//#region src/client/index.ts
-function isNumeric(str) {
-	if (str == null) return false;
-	return `${+str}` === `${str}`;
-}
-async function getDevToolsRpcClient(options = {}) {
-	const { baseURL = "/__vite_devtools__/api/" } = options;
-	const urls = Array.isArray(baseURL) ? baseURL : [baseURL];
-	let connectionMeta = options.connectionMeta;
-	if (!connectionMeta) {
-		const errors = [];
-		for (const url$1 of urls) try {
-			connectionMeta = await fetch(`${url$1}connection.json`).then((r) => r.json());
-			break;
-		} catch (e) {
-			errors.push(e);
-		}
-		if (!connectionMeta) throw new Error(`Failed to get connection meta from ${urls.join(", ")}`, { cause: errors });
-	}
-	const url = isNumeric(connectionMeta.websocket) ? `${location.protocol.replace("http", "ws")}//${location.hostname}:${connectionMeta.websocket}` : connectionMeta.websocket;
-	const rpc = createRpcClient({}, {
-		preset: createWsRpcPreset({
-			url,
-			...options.wsOptions
-		}),
-		...options.rpcOptions
-	});
-	return {
-		connectionMeta,
-		rpc
-	};
-}
-
-//#endregion
-export { getDevToolsRpcClient };

package/dist/index.d.ts

@@ -1,18 +0,0 @@
-import { BirpcFn, BirpcReturn, ConnectionMeta, DevToolsCapabilities, DevToolsDockEntry, DevToolsDockEntryBase, DevToolsDockHost, DevToolsNodeContext, DevToolsPluginOptions, DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, DevToolsViewAction, DevToolsViewIframe, DevToolsViewWebComponent, EntriesToObject, RpcDefinitionsFilter, RpcDefinitionsToFunctions, RpcFunctionDefinition, RpcFunctionSetupResult, RpcFunctionType, RpcFunctionsHost, Thenable } from "./rpc-ls6mUIa2.js";
-import { Plugin } from "vite";
-
-//#region src/types/vite-augment.d.ts
-declare module 'vite' {
-  interface Plugin {
-    devtools?: DevToolsPluginOptions;
-  }
-}
-interface PluginWithDevTools extends Plugin {
-  devtools?: DevToolsPluginOptions;
-}
-//#endregion
-//#region src/utils/rpc.d.ts
-declare function defineRpcFunction<NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN>): RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN>;
-declare function getRpcHandler<NAME extends string, TYPE extends RpcFunctionType, ARGS extends any[], RETURN = void>(definition: RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN>, context: DevToolsNodeContext): Promise<(...args: ARGS) => RETURN>;
-//#endregion
-export { BirpcFn, BirpcReturn, ConnectionMeta, DevToolsCapabilities, DevToolsDockEntry, DevToolsDockEntryBase, DevToolsDockHost, DevToolsNodeContext, DevToolsPluginOptions, DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, DevToolsViewAction, DevToolsViewIframe, DevToolsViewWebComponent, EntriesToObject, PluginWithDevTools, RpcDefinitionsFilter, RpcDefinitionsToFunctions, RpcFunctionDefinition, RpcFunctionSetupResult, RpcFunctionType, RpcFunctionsHost, Thenable, defineRpcFunction, getRpcHandler };

package/dist/index.js

@@ -1,17 +0,0 @@
-//#region src/utils/rpc.ts
-function defineRpcFunction(definition) {
-	return definition;
-}
-async function getRpcHandler(definition, context) {
-	if (definition.handler) return definition.handler;
-	if (definition.__resolved?.handler) return definition.__resolved.handler;
-	definition.__promise ??= Promise.resolve(definition.setup(context)).then((r) => {
-		definition.__resolved = r;
-		definition.__promise = void 0;
-		return r;
-	});
-	return (definition.__resolved ??= await definition.__promise).handler;
-}
-
-//#endregion
-export { defineRpcFunction, getRpcHandler };

package/dist/rpc-ls6mUIa2.d.ts

@@ -1,118 +0,0 @@
-import { BirpcFn, BirpcReturn as BirpcReturn$1 } from "birpc";
-import { 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 {
-  register: (entry: DevToolsDockEntry) => void;
-  values: () => DevToolsDockEntry[];
-}
-interface DevToolsDockEntryBase {
-  id: string;
-  title: string;
-  icon: 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;
-}
-interface DevToolsViewWebComponent extends DevToolsDockEntryBase {
-  type: 'webcomponent';
-  from: string;
-  import: string;
-}
-interface DevToolsViewAction extends DevToolsDockEntryBase {
-  type: 'action';
-  importFrom: string;
-  /**
-   * @default 'default'
-   */
-  importName?: string;
-}
-type DevToolsDockEntry = DevToolsViewIframe | DevToolsViewWebComponent | DevToolsViewAction;
-//#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;
-  /**
-   * 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;
-  staticDirs: {
-    baseUrl: string;
-    distDir: string;
-  }[];
-}
-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;
-}
-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
-export { type BirpcFn, type BirpcReturn$1 as BirpcReturn, ConnectionMeta, DevToolsCapabilities, DevToolsDockEntry, DevToolsDockEntryBase, DevToolsDockHost, DevToolsNodeContext, DevToolsPluginOptions, DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, DevToolsViewAction, DevToolsViewIframe, DevToolsViewWebComponent, EntriesToObject, RpcDefinitionsFilter, RpcDefinitionsToFunctions, RpcFunctionDefinition, RpcFunctionSetupResult, RpcFunctionType, RpcFunctionsHost, Thenable };