docs: add WeakMap pattern for sharing state across RPC functions (#259)

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: antfu

docs/kit/rpc.md

@@ -393,6 +393,74 @@ export default function setup(ctx: DockClientScriptContext) {
 }
 ```
 
+### Sharing State Across RPC Functions
+
+When multiple RPC functions need access to the same plugin-specific state (a manager instance, plugin options, cached data, etc.), use a `WeakMap` keyed by `DevToolsNodeContext` to store and retrieve that state. This avoids mutating the base context object and keeps your plugin state scoped and garbage-collectable.
+
+Create a helper file with get/set functions:
+
+```ts
+// src/node/rpc/context.ts
+import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+
+interface MyPluginContext {
+  dataDir: string
+  manager: DataManager
+}
+
+const pluginContext = new WeakMap<DevToolsNodeContext, MyPluginContext>()
+
+export function getPluginContext(ctx: DevToolsNodeContext): MyPluginContext {
+  const value = pluginContext.get(ctx)
+  if (!value)
+    throw new Error('Plugin context not initialized')
+  return value
+}
+
+export function setPluginContext(ctx: DevToolsNodeContext, value: MyPluginContext) {
+  pluginContext.set(ctx, value)
+}
+```
+
+Initialize the state in your plugin's `devtools.setup`, then access it from any RPC function's `setup`:
+
+::: code-group
+
+```ts [plugin.ts]
+import { rpcFunctions } from './rpc'
+import { setPluginContext } from './rpc/context'
+
+const plugin: Plugin = {
+  devtools: {
+    setup(ctx) {
+      setPluginContext(ctx, {
+        dataDir: resolve(ctx.cwd, 'data'),
+        manager: new DataManager(),
+      })
+      rpcFunctions.forEach(fn => ctx.rpc.register(fn))
+    },
+  },
+}
+```
+
+```ts [functions/get-data.ts]
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+import { getPluginContext } from '../context'
+
+export const getData = defineRpcFunction({
+  name: 'my-plugin:get-data',
+  type: 'query',
+  setup: (ctx) => {
+    const { manager } = getPluginContext(ctx)
+    return {
+      handler: async () => manager.getData(),
+    }
+  },
+})
+```
+
+:::
+
 ### Global Client Context
 
 Use `getDevToolsClientContext()` to access the client context (`DevToolsClientContext`) from anywhere on the client side. This is set automatically when DevTools initializes in embedded or standalone mode.

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

@@ -85,6 +85,57 @@ defineRpcFunction({
 })
 ```
 
+## Sharing State Across RPC Functions
+
+When multiple RPC functions need shared plugin state (manager instances, options, cached data), use a `WeakMap<DevToolsNodeContext, T>` with get/set helpers instead of mutating the context object:
+
+```ts
+// src/node/rpc/context.ts
+import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+
+interface MyPluginContext {
+  dataDir: string
+  manager: DataManager
+}
+
+const pluginContext = new WeakMap<DevToolsNodeContext, MyPluginContext>()
+
+export function getPluginContext(ctx: DevToolsNodeContext): MyPluginContext {
+  const value = pluginContext.get(ctx)
+  if (!value)
+    throw new Error('Plugin context not initialized')
+  return value
+}
+
+export function setPluginContext(ctx: DevToolsNodeContext, value: MyPluginContext) {
+  pluginContext.set(ctx, value)
+}
+```
+
+Initialize in plugin setup, access in RPC functions:
+
+```ts
+// Plugin setup
+devtools: {
+  setup(ctx) {
+    setPluginContext(ctx, { dataDir: resolve(ctx.cwd, 'data'), manager: new DataManager() })
+    rpcFunctions.forEach(fn => ctx.rpc.register(fn))
+  },
+}
+
+// RPC function
+const getData = defineRpcFunction({
+  name: 'my-plugin:get-data',
+  type: 'query',
+  setup: (ctx) => {
+    const { manager } = getPluginContext(ctx)
+    return {
+      handler: async () => manager.getData(),
+    }
+  },
+})
+```
+
 ## Broadcasting Patterns
 
 ### Basic Broadcast