feat(kit)!: remove deprecated APIs for v0.2.0

antfu · antfu · commit 8e98730af53b · 2026-05-19T10:48:56.000+09:00
Removes the deprecated `DevToolsNodeContext` alias, the `DevToolsLog*` type
aliases, the `DockClientScriptContext.logs` property, and the
`WhenContext`/`WhenExpression` re-export from the kit's main types barrel.
The `utils/*` subpath exports remain as canonical re-exports of
`devframe/utils/*` with their `@deprecated` markers dropped. Adds
`MIGRATION.md` with the 0.1 → 0.2 mapping table.
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -0,0 +1,52 @@
+# Migration Guide
+
+## 0.1 → 0.2
+
+### `@vitejs/devtools-kit`
+
+The deprecated aliases introduced in 0.1 have been removed. Update imports and references as follows.
+
+#### Message types
+
+The `DevToolsLog*` types were renamed to `DevToolsMessage*` in 0.1. The old names are now gone.
+
+| Removed | Replacement |
+| --- | --- |
+| `DevToolsLogLevel` | `DevToolsMessageLevel` |
+| `DevToolsLogEntryFrom` | `DevToolsMessageEntryFrom` |
+| `DevToolsLogElementPosition` | `DevToolsMessageElementPosition` |
+| `DevToolsLogFilePosition` | `DevToolsMessageFilePosition` |
+| `DevToolsLogEntry` | `DevToolsMessageEntry` |
+| `DevToolsLogEntryInput` | `DevToolsMessageEntryInput` |
+| `DevToolsLogHandle` | `DevToolsMessageHandle` |
+| `DevToolsLogsClient` | `DevToolsMessagesClient` |
+| `DevToolsLogsHost` | `DevToolsMessagesHost` |
+
+#### Node context type
+
+```diff
+- import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
++ import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
+```
+
+The framework-neutral `DevToolsNodeContext` still lives upstream at `devframe/types` and is unchanged.
+
+#### Dock client script context
+
+```diff
+  defineDockClientScript((ctx) => {
+-   ctx.logs.add({ ... })
++   ctx.messages.add({ ... })
+  })
+```
+
+#### `WhenContext` / `WhenExpression`
+
+These types are no longer re-exported from `@vitejs/devtools-kit`. Import them from devframe:
+
+```diff
+- import type { WhenContext, WhenExpression } from '@vitejs/devtools-kit'
++ import type { WhenContext, WhenExpression } from 'devframe/utils/when'
+```
+
+The `@vitejs/devtools-kit/utils/when` subpath remains and re-exports these types alongside `evaluateWhen` and `resolveContextValue`.
diff --git a/docs/errors/DTK0014.md b/docs/errors/DTK0014.md
@@ -10,7 +10,7 @@ outline: deep
 
 ## Cause
 
-This error is thrown by `createDevToolsContext()` when a Vite plugin's `devtools.setup()` hook throws during initialization. The DevTools context iterates over all Vite plugins that define a `devtools` property and calls their `setup()` hook with the `DevToolsNodeContext`. If the hook throws, the error is caught, wrapped with this diagnostic (preserving the original error as `cause`), and re-thrown -- halting DevTools initialization.
+This error is thrown by `createDevToolsContext()` when a Vite plugin's `devtools.setup()` hook throws during initialization. The DevTools context iterates over all Vite plugins that define a `devtools` property and calls their `setup()` hook with the `ViteDevToolsNodeContext`. If the hook throws, the error is caught, wrapped with this diagnostic (preserving the original error as `cause`), and re-thrown -- halting DevTools initialization.
 
 Plugins may be skipped entirely if their `devtools.capabilities` configuration indicates they do not support the current mode (dev or build).
 
diff --git a/docs/kit/devtools-plugin.md b/docs/kit/devtools-plugin.md
@@ -68,7 +68,7 @@ export default function myPlugin(): Plugin {
 
 ## DevTools context
 
-The `setup` function receives a `DevToolsNodeContext` providing access to every DevTools API:
+The `setup` function receives a `ViteDevToolsNodeContext` providing access to every DevTools API:
 
 ```ts
 const plugin: Plugin = {
diff --git a/docs/kit/rpc.md b/docs/kit/rpc.md
@@ -78,7 +78,7 @@ const getModule = defineRpcFunction({
 
 ### Context in setup
 
-The `setup` function receives the full `DevToolsNodeContext`:
+The `setup` function receives the full `ViteDevToolsNodeContext`:
 
 ```ts
 setup: (ctx) => {
@@ -255,15 +255,15 @@ Use a shared context helper (for example `WeakMap`-backed `set/get`) to provide
 
 ```ts
 // src/node/rpc/context.ts
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 
-const rpcContext = new WeakMap<DevToolsNodeContext, { targetDir: string }>()
+const rpcContext = new WeakMap<ViteDevToolsNodeContext, { targetDir: string }>()
 
-export function setRpcContext(context: DevToolsNodeContext, options: { targetDir: string }) {
+export function setRpcContext(context: ViteDevToolsNodeContext, options: { targetDir: string }) {
   rpcContext.set(context, options)
 }
 
-export function getRpcContext(context: DevToolsNodeContext) {
+export function getRpcContext(context: ViteDevToolsNodeContext) {
   const value = rpcContext.get(context)
   if (!value)
     throw new Error('Missing RPC context')
@@ -381,29 +381,29 @@ export default function setup(ctx: DockClientScriptContext) {
 
 ### Sharing state across RPC functions
 
-When multiple RPC functions need the same plugin-specific state (a manager instance, plugin options, cached data), key a `WeakMap` by `DevToolsNodeContext`. This keeps the plugin state scoped, garbage-collectable, and out of the base context.
+When multiple RPC functions need the same plugin-specific state (a manager instance, plugin options, cached data), key a `WeakMap` by `ViteDevToolsNodeContext`. This keeps the plugin state scoped, garbage-collectable, and out of the base context.
 
 Create a helper file with get/set functions:
 
 ```ts
 // src/node/rpc/context.ts
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 
 interface MyPluginContext {
   dataDir: string
   manager: DataManager
 }
 
-const pluginContext = new WeakMap<DevToolsNodeContext, MyPluginContext>()
+const pluginContext = new WeakMap<ViteDevToolsNodeContext, MyPluginContext>()
 
-export function getPluginContext(ctx: DevToolsNodeContext): MyPluginContext {
+export function getPluginContext(ctx: ViteDevToolsNodeContext): MyPluginContext {
   const value = pluginContext.get(ctx)
   if (!value)
     throw new Error('Plugin context not initialized')
   return value
 }
 
-export function setPluginContext(ctx: DevToolsNodeContext, value: MyPluginContext) {
+export function setPluginContext(ctx: ViteDevToolsNodeContext, value: MyPluginContext) {
   pluginContext.set(ctx, value)
 }
 ```
diff --git a/examples/plugin-file-explorer/src/node/rpc/context.ts b/examples/plugin-file-explorer/src/node/rpc/context.ts
@@ -1,16 +1,16 @@
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { KitPluginFileExplorerResolvedOptions } from '../types'
 
-const fileExplorerOptions = new WeakMap<DevToolsNodeContext, KitPluginFileExplorerResolvedOptions>()
+const fileExplorerOptions = new WeakMap<ViteDevToolsNodeContext, KitPluginFileExplorerResolvedOptions>()
 
 export function setFileExplorerOptions(
-  context: DevToolsNodeContext,
+  context: ViteDevToolsNodeContext,
   options: KitPluginFileExplorerResolvedOptions,
 ): void {
   fileExplorerOptions.set(context, options)
 }
 
-export function getFileExplorerOptions(context: DevToolsNodeContext): KitPluginFileExplorerResolvedOptions {
+export function getFileExplorerOptions(context: ViteDevToolsNodeContext): KitPluginFileExplorerResolvedOptions {
   const options = fileExplorerOptions.get(context)
   if (!options) {
     throw new Error('[kit-plugin-file-explorer] Missing plugin options in context. Ensure setup calls setFileExplorerOptions(context, options) before registering RPC functions.')
diff --git a/packages/core/src/client/webcomponents/state/commands.ts b/packages/core/src/client/webcomponents/state/commands.ts
@@ -1,6 +1,7 @@
-import type { DevToolsClientCommand, DevToolsCommandEntry, DevToolsCommandKeybinding, DevToolsDocksUserSettings, DevToolsServerCommandEntry, WhenContext } from '@vitejs/devtools-kit'
+import type { DevToolsClientCommand, DevToolsCommandEntry, DevToolsCommandKeybinding, DevToolsDocksUserSettings, DevToolsServerCommandEntry } from '@vitejs/devtools-kit'
 import type { CommandsContext, DevToolsRpcClient } from '@vitejs/devtools-kit/client'
 import type { SharedState } from 'devframe/utils/shared-state'
+import type { WhenContext } from 'devframe/utils/when'
 import type { ShallowRef } from 'vue'
 import { evaluateWhen } from 'devframe/utils/when'
 import { computed, markRaw, reactive, ref } from 'vue'
diff --git a/packages/core/src/client/webcomponents/state/context.ts b/packages/core/src/client/webcomponents/state/context.ts
@@ -1,6 +1,7 @@
-import type { DevToolsClientCommand, WhenContext } from '@vitejs/devtools-kit'
+import type { DevToolsClientCommand } from '@vitejs/devtools-kit'
 import type { CommandsContext, DevToolsRpcClient, DockClientScriptContext, DockEntryState, DockPanelStorage, DocksContext } from '@vitejs/devtools-kit/client'
 import type { SharedState } from 'devframe/utils/shared-state'
+import type { WhenContext } from 'devframe/utils/when'
 import type { Ref } from 'vue'
 import type { DevToolsDocksUserSettings } from './dock-settings'
 import { DEFAULT_STATE_USER_SETTINGS } from '@vitejs/devtools-kit/constants'
diff --git a/packages/core/src/client/webcomponents/state/dock-settings.ts b/packages/core/src/client/webcomponents/state/dock-settings.ts
@@ -1,5 +1,6 @@
-import type { DevToolsDockEntriesGrouped, DevToolsDockEntry, DevToolsDocksUserSettings, WhenContext } from '@vitejs/devtools-kit'
+import type { DevToolsDockEntriesGrouped, DevToolsDockEntry, DevToolsDocksUserSettings } from '@vitejs/devtools-kit'
 import type { Immutable } from 'devframe/utils/shared-state'
+import type { WhenContext } from 'devframe/utils/when'
 import { evaluateWhen } from 'devframe/utils/when'
 import { DEFAULT_CATEGORIES_ORDER } from '../constants'
 
diff --git a/packages/core/src/client/webcomponents/state/keybindings.ts b/packages/core/src/client/webcomponents/state/keybindings.ts
@@ -1,7 +1,6 @@
 import type { DevToolsCommandEntry, DevToolsCommandKeybinding } from '@vitejs/devtools-kit'
 
-// Re-export when utilities from kit
-export type { WhenContext } from '@vitejs/devtools-kit'
+export type { WhenContext } from 'devframe/utils/when'
 export { evaluateWhen, resolveContextValue } from 'devframe/utils/when'
 
 export const isMac = typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform ?? '')
diff --git a/packages/core/src/node/__tests__/open-in-editor.test.ts b/packages/core/src/node/__tests__/open-in-editor.test.ts
@@ -1,4 +1,4 @@
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import { resolve } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { openInEditor } from '../rpc/public/open-in-editor'
@@ -11,7 +11,7 @@ vi.mock('devframe/utils/launch-editor', () => ({
 describe('openInEditor – path traversal protection', () => {
   const cwd = resolve('/project/root')
   const workspaceRoot = resolve('/project')
-  const mockContext = { cwd, workspaceRoot } as DevToolsNodeContext
+  const mockContext = { cwd, workspaceRoot } as ViteDevToolsNodeContext
 
   async function getHandler() {
     const setup = openInEditor.setup!
diff --git a/packages/core/src/node/build-static.ts b/packages/core/src/node/build-static.ts
@@ -1,6 +1,6 @@
 /* eslint-disable no-console */
 
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import { existsSync } from 'node:fs'
 import fs from 'node:fs/promises'
 import {
@@ -17,7 +17,7 @@ import { dirClientStandalone } from '../dirs'
 import { MARK_NODE } from './constants'
 
 export interface BuildStaticOptions {
-  context: DevToolsNodeContext
+  context: ViteDevToolsNodeContext
   outDir: string
   withApp?: boolean
 }
diff --git a/packages/core/src/node/plugins/build.ts b/packages/core/src/node/plugins/build.ts
@@ -1,6 +1,6 @@
 /* eslint-disable no-console */
 
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { Plugin, ResolvedConfig } from 'vite'
 import { colors as c } from 'devframe/utils/colors'
 import { resolve } from 'pathe'
@@ -11,7 +11,7 @@ export interface DevToolsBuildOptions {
 }
 
 export function DevToolsBuild(options: DevToolsBuildOptions = {}): Plugin {
-  let context: DevToolsNodeContext
+  let context: ViteDevToolsNodeContext
   let resolvedConfig: ResolvedConfig
 
   return {
diff --git a/packages/core/src/node/plugins/server.ts b/packages/core/src/node/plugins/server.ts
@@ -1,4 +1,4 @@
-import type { ClientScriptEntry, DevToolsDockEntry, DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ClientScriptEntry, DevToolsDockEntry, ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { Plugin } from 'vite'
 import {
   DEVTOOLS_DOCK_IMPORTS_VIRTUAL_ID,
@@ -36,7 +36,7 @@ export function renderDockImportsMap(docks: Iterable<DevToolsDockEntry>): string
 }
 
 export function DevToolsServer(): Plugin {
-  let context: DevToolsNodeContext
+  let context: ViteDevToolsNodeContext
   return {
     name: 'vite:devtools:server',
     enforce: 'post',
diff --git a/packages/core/src/node/standalone.ts b/packages/core/src/node/standalone.ts
@@ -1,4 +1,4 @@
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { Plugin, ResolvedConfig } from 'vite'
 import process from 'node:process'
 import { createDevToolsContext } from './context'
@@ -14,7 +14,7 @@ export interface StandaloneDevToolsOptions {
 
 export async function startStandaloneDevTools(options: StandaloneDevToolsOptions = {}): Promise<{
   config: ResolvedConfig
-  context: DevToolsNodeContext
+  context: ViteDevToolsNodeContext
 }> {
   const {
     cwd = process.cwd(),
diff --git a/packages/core/src/node/ws.ts b/packages/core/src/node/ws.ts
@@ -1,5 +1,5 @@
 /* eslint-disable no-console */
-import type { ConnectionMeta, DevToolsNodeContext, DevToolsNodeRpcSession, DevToolsRpcClientFunctions, DevToolsRpcServerFunctions } from '@vitejs/devtools-kit'
+import type { ConnectionMeta, DevToolsNodeRpcSession, DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import type { RpcFunctionsHost } from 'devframe/node'
 import type { WebSocket } from 'ws'
 import { AsyncLocalStorage } from 'node:async_hooks'
@@ -20,10 +20,10 @@ export interface CreateWsServerOptions {
   websocket: {
     port?: number
     host: string
-    https?: DevToolsNodeContext['viteConfig']['server']['https'] | false
+    https?: ViteDevToolsNodeContext['viteConfig']['server']['https'] | false
   }
   base?: string
-  context: DevToolsNodeContext
+  context: ViteDevToolsNodeContext
 }
 
 const ANONYMOUS_SCOPE = 'vite:anonymous:'
diff --git a/packages/kit/src/client/client-script.ts b/packages/kit/src/client/client-script.ts
@@ -13,8 +13,4 @@ export interface DockClientScriptContext extends DocksContext {
    * Messages client scoped to this dock entry's source
    */
   messages: DevToolsMessagesClient
-  /**
-   * @deprecated Use `messages` instead. Will be removed in a future release.
-   */
-  readonly logs: DevToolsMessagesClient
 }
diff --git a/packages/kit/src/define.ts b/packages/kit/src/define.ts
@@ -1,7 +1,8 @@
-import type { DevToolsDockUserEntry, DevToolsNodeContext, DevToolsServerCommandInput, JsonRenderSpec, WhenContext, WhenExpression } from './types'
+import type { WhenContext, WhenExpression } from 'devframe/utils/when'
+import type { DevToolsDockUserEntry, DevToolsServerCommandInput, JsonRenderSpec, ViteDevToolsNodeContext } from './types'
 import { createDefineWrapperWithContext } from 'devframe/rpc'
 
-export const defineRpcFunction = createDefineWrapperWithContext<DevToolsNodeContext>()
+export const defineRpcFunction = createDefineWrapperWithContext<ViteDevToolsNodeContext>()
 
 export function defineCommand<const W extends string = ''>(
   command: Omit<DevToolsServerCommandInput, 'when'> & { when?: WhenExpression<WhenContext, W> },
diff --git a/packages/kit/src/types/index.ts b/packages/kit/src/types/index.ts
@@ -2,7 +2,6 @@
 // from the kit's main `types` barrel.
 export type { CreateKitContextOptions, KitNodeContext } from '../node/context'
 
-export type { WhenContext, WhenExpression } from '../utils/when'
 export * from './commands'
 export * from './docks'
 export * from './json-render'
diff --git a/packages/kit/src/types/messages.ts b/packages/kit/src/types/messages.ts
@@ -144,22 +144,3 @@ export interface DevToolsMessagesHost {
    */
   clear: () => Promise<void>
 }
-
-/** @deprecated alias of {@link DevToolsMessageLevel}. Will be removed in a future release. */
-export type DevToolsLogLevel = DevToolsMessageLevel
-/** @deprecated alias of {@link DevToolsMessageEntryFrom}. Will be removed in a future release. */
-export type DevToolsLogEntryFrom = DevToolsMessageEntryFrom
-/** @deprecated alias of {@link DevToolsMessageElementPosition}. Will be removed in a future release. */
-export type DevToolsLogElementPosition = DevToolsMessageElementPosition
-/** @deprecated alias of {@link DevToolsMessageFilePosition}. Will be removed in a future release. */
-export type DevToolsLogFilePosition = DevToolsMessageFilePosition
-/** @deprecated alias of {@link DevToolsMessageEntry}. Will be removed in a future release. */
-export type DevToolsLogEntry = DevToolsMessageEntry
-/** @deprecated alias of {@link DevToolsMessageEntryInput}. Will be removed in a future release. */
-export type DevToolsLogEntryInput = DevToolsMessageEntryInput
-/** @deprecated alias of {@link DevToolsMessageHandle}. Will be removed in a future release. */
-export type DevToolsLogHandle = DevToolsMessageHandle
-/** @deprecated alias of {@link DevToolsMessagesClient}. Will be removed in a future release. */
-export type DevToolsLogsClient = DevToolsMessagesClient
-/** @deprecated alias of {@link DevToolsMessagesHost}. Will be removed in a future release. */
-export type DevToolsLogsHost = DevToolsMessagesHost
diff --git a/packages/kit/src/types/vite-plugin.ts b/packages/kit/src/types/vite-plugin.ts
@@ -22,9 +22,3 @@ export interface ViteDevToolsNodeContext extends KitNodeContext {
   readonly viteConfig: ResolvedConfig
   readonly viteServer?: ViteDevServer
 }
-
-/**
- * @deprecated — alias of {@link ViteDevToolsNodeContext}. Exists for one
- * release cycle while callers migrate.
- */
-export type DevToolsNodeContext = ViteDevToolsNodeContext
diff --git a/packages/kit/src/utils/events.ts b/packages/kit/src/utils/events.ts
@@ -1,2 +1 @@
-/** @deprecated Import from `devframe/utils/events` instead. */
 export { createEventEmitter } from 'devframe/utils/events'
diff --git a/packages/kit/src/utils/human-id.ts b/packages/kit/src/utils/human-id.ts
@@ -1,2 +1 @@
-/** @deprecated Import from `devframe/utils/human-id` instead. */
 export { humanId } from 'devframe/utils/human-id'
diff --git a/packages/kit/src/utils/nanoid.ts b/packages/kit/src/utils/nanoid.ts
@@ -1,2 +1 @@
-/** @deprecated Import from `devframe/utils/nanoid` instead. */
 export { nanoid } from 'devframe/utils/nanoid'
diff --git a/packages/kit/src/utils/shared-state.ts b/packages/kit/src/utils/shared-state.ts
@@ -1,6 +1,4 @@
-/** @deprecated Import from `devframe/utils/shared-state` instead. */
 export { createSharedState } from 'devframe/utils/shared-state'
-/** @deprecated Import from `devframe/utils/shared-state` instead. */
 export type {
   Immutable,
   ImmutableArray,
diff --git a/packages/kit/src/utils/when.ts b/packages/kit/src/utils/when.ts
@@ -1,4 +1,2 @@
-/** @deprecated Import from `devframe/utils/when` instead. */
 export { evaluateWhen, resolveContextValue } from 'devframe/utils/when'
-/** @deprecated Import from `devframe/utils/when` instead. */
 export type { WhenContext, WhenExpression } from 'devframe/utils/when'
diff --git a/packages/rolldown/src/node/rpc/utils.ts b/packages/rolldown/src/node/rpc/utils.ts
@@ -1,13 +1,13 @@
-import type { DevToolsNodeContext } from '@vitejs/devtools-kit'
+import type { ViteDevToolsNodeContext } from '@vitejs/devtools-kit'
 import { existsSync } from 'node:fs'
 import process from 'node:process'
 import { join } from 'pathe'
 import { diagnostics } from '../diagnostics'
 import { RolldownLogsManager } from '../rolldown/logs-manager'
 
-const weakMap = new WeakMap<DevToolsNodeContext, RolldownLogsManager>()
+const weakMap = new WeakMap<ViteDevToolsNodeContext, RolldownLogsManager>()
 
-export function getLogsManager(context: DevToolsNodeContext): RolldownLogsManager {
+export function getLogsManager(context: ViteDevToolsNodeContext): RolldownLogsManager {
   let manager = weakMap.get(context)!
   if (!manager) {
     const dirs = [
@@ -23,6 +23,6 @@ export function getLogsManager(context: DevToolsNodeContext): RolldownLogsManage
   return manager
 }
 
-export function setLogsManager(context: DevToolsNodeContext, manager: RolldownLogsManager) {
+export function setLogsManager(context: ViteDevToolsNodeContext, manager: RolldownLogsManager) {
   weakMap.set(context, manager)
 }
diff --git a/skills/vite-devtools-kit/SKILL.md b/skills/vite-devtools-kit/SKILL.md
diff --git a/skills/vite-devtools-kit/references/rpc-patterns.md b/skills/vite-devtools-kit/references/rpc-patterns.md
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/client.snapshot.d.ts b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/client.snapshot.d.ts
diff --git a/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts b/test/__snapshots__/tsnapi/@vitejs/devtools-kit/index.snapshot.d.ts
