chore: update

Author: antfu

docs/kit/index.md

@@ -19,6 +19,8 @@ DevTools Kit offers a complete toolkit for building DevTools integrations:
 
 - **🔌 [Built-in RPC Layer](#remote-procedure-calls-rpc)**: Type-safe bidirectional communication between your Node.js server and browser clients, eliminating the need to set up WebSocket connections or message passing manually
 
+- **🔗 [Shared State](#shared-state)**: Share data between server and client with automatic synchronization
+
 - **🌐 Isomorphic Views Hosting**: Write your UI once and deploy it anywhere—as embedded floating panels, browser extension panels, standalone webpages, or even deployable SPAs for sharing build snapshots (work in progress).
 
 ## Why DevTools Kit?
@@ -418,6 +420,89 @@ rpc.client.register({
 })
 ```
 
+### Shared State
+
+The DevTools Kit provides a built-in shared state system that enables you to share data between the server and client with automatic synchronization.
+
+On the server side, you can get the shared state using `ctx.rpc.sharedState.get(name, options)`:
+
+```ts {6-10}
+export default function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',
+    devtools: {
+      async setup(ctx) {
+        // Get the shared state
+        const state = await ctx.rpc.sharedState.get('my-plugin:state', {
+          initialValue: {
+            count: 0,
+            name: 'John Doe',
+          },
+        })
+
+        // Use .value() to get the current state
+        console.log(state.value()) // { count: 0, name: 'John Doe' }
+
+        setTimeout(() => {
+          // Mutate the shared state, changes will be automatically synchronized to all the connected clients
+          state.mutate((state) => {
+            state.count += 1
+          })
+        }, 1000)
+      },
+    },
+  }
+}
+```
+
+<details>
+<summary>Type-safe shared state</summary>
+
+The shared state is type-safe, you can get the state with the type of the initial value. To do so, you need to extend the `DevToolsRpcSharedStates` interface in your plugin's type definitions.
+
+```ts [src/types.ts]
+import '@vitejs/devtools-kit'
+
+declare module '@vitejs/devtools-kit' {
+  interface DevToolsRpcSharedStates {
+    'my-plugin:state': { count: number, name: string }
+  }
+}
+```
+
+</details>
+
+On the client side, you can get the shared state using `client.rpc.sharedState.get(name)`:
+
+```ts {6-10}
+import { getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
+
+const client = await getDevToolsRpcClient()
+
+const state = await client.rpc.sharedState.get('my-plugin:state')
+
+console.log(state.value()) // { count: 0, name: 'John Doe' }
+
+// Use .on('updated') to subscribe to changes
+state.on('updated', (newState) => {
+  console.log(newState) // { count: 1, name: 'John Doe' }
+})
+```
+
+For example, if you use Vue, you can wrap it into a reactive ref:
+
+```ts {6-10}
+import { shallowRef } from 'vue'
+
+const sharedState = await client.rpc.sharedState.get('my-plugin:state')
+const state = shallowRef(sharedState.value())
+sharedState.on('updated', (newState) => {
+  state.value = newState
+})
+
+// Now the `state` ref will be updated automatically when the shared state changes
+```
+
 ## References
 
 The docs might not cover all the details, please help us to improve it by submitting PRs. And in the meantime, you can refer to the following existing DevTools integrations for reference (but note they might not always be up to date with the latest API changes):

packages/core/playground/src/pages/devtools.vue

@@ -15,7 +15,7 @@ onMounted(async () => {
     isTrustedRef.value = isTrusted
   })
 
-  const state = await client.sharedState.get<{ count: number }>('counter')
+  const state = await client.sharedState.get('counter')
 
   increment = () => {
     state.mutate((state) => {

packages/core/playground/vite.config.ts

@@ -11,6 +11,12 @@ import { DevToolsViteUI } from '../../vite/src/node'
 import { DevTools } from '../src'
 import { buildCSS } from '../src/client/webcomponents/scripts/build-css'
 
+declare module '@vitejs/devtools-kit' {
+  interface DevToolsRpcSharedStates {
+    counter: { count: number }
+  }
+}
+
 // https://vite.dev/config/
 export default defineConfig({
   define: {

packages/core/src/node/rpc/internal/state/get.ts

@@ -1,4 +1,4 @@
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { DevToolsNodeContext, DevToolsRpcSharedStates } from '@vitejs/devtools-kit'
 import { defineRpcFunction } from '@vitejs/devtools-kit'
 
 export const sharedStateGet = defineRpcFunction({
@@ -7,7 +7,7 @@ export const sharedStateGet = defineRpcFunction({
   setup: (context: DevToolsNodeContext) => {
     return {
       handler: async (key: string) => {
-        const state = await context.rpc.sharedState.get(key)
+        const state = await context.rpc.sharedState.get(key as keyof DevToolsRpcSharedStates)
         return state.value()
       },
     }

packages/core/src/node/rpc/internal/state/patch.ts

@@ -1,4 +1,4 @@
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { DevToolsNodeContext, DevToolsRpcSharedStates } from '@vitejs/devtools-kit'
 import type { SharedStatePatch } from '@vitejs/devtools-kit/utils/shared-state'
 import { defineRpcFunction } from '@vitejs/devtools-kit'
 
@@ -8,7 +8,7 @@ export const sharedStatePatch = defineRpcFunction({
   setup: (context: DevToolsNodeContext) => {
     return {
       handler: async (key: string, patches: SharedStatePatch[], syncId: string) => {
-        const state = await context.rpc.sharedState.get(key)
+        const state = await context.rpc.sharedState.get(key as keyof DevToolsRpcSharedStates)
         state.patch(patches, syncId)
       },
     }

packages/core/src/node/rpc/internal/state/set.ts

@@ -1,4 +1,4 @@
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { DevToolsNodeContext, DevToolsRpcSharedStates } from '@vitejs/devtools-kit'
 import { defineRpcFunction } from '@vitejs/devtools-kit'
 
 export const sharedStateSet = defineRpcFunction({
@@ -7,7 +7,7 @@ export const sharedStateSet = defineRpcFunction({
   setup: (context: DevToolsNodeContext) => {
     return {
       handler: async (key: string, value: any, syncId: string) => {
-        const state = await context.rpc.sharedState.get(key)
+        const state = await context.rpc.sharedState.get(key as keyof DevToolsRpcSharedStates)
         state.mutate(() => value, syncId)
       },
     }

packages/kit/src/types/rpc-augments.ts

@@ -7,3 +7,8 @@ export interface DevToolsRpcClientFunctions {}
  * To be extended
  */
 export interface DevToolsRpcServerFunctions {}
+
+/**
+ * To be extended
+ */
+export interface DevToolsRpcSharedStates {}

packages/kit/src/types/rpc.ts

@@ -2,7 +2,7 @@ import type { DevToolsNodeRpcSessionMeta } from '@vitejs/devtools-rpc/presets/ws
 import type { BirpcReturn } from 'birpc'
 import type { RpcFunctionsCollectorBase } from 'birpc-x'
 import type { SharedState } from '../utils/shared-state'
-import type { DevToolsRpcClientFunctions, DevToolsRpcServerFunctions } from './rpc-augments'
+import type { DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, DevToolsRpcSharedStates } from './rpc-augments'
 import type { DevToolsNodeContext } from './vite-plugin'
 
 export type { DevToolsNodeRpcSessionMeta }
@@ -49,5 +49,5 @@ export interface RpcSharedStateGetOptions<T> {
 }
 
 export interface RpcSharedStateHost {
-  get: <T extends object>(key: string, options?: RpcSharedStateGetOptions<T>) => Promise<SharedState<T>>
+  get: <T extends keyof DevToolsRpcSharedStates>(key: T, options?: RpcSharedStateGetOptions<DevToolsRpcSharedStates[T]>) => Promise<SharedState<DevToolsRpcSharedStates[T]>>
 }