fix(core): declare client module resolution before plugin setup (#582)

Author: morinokami

packages/core/src/node/__tests__/context-client-module-resolution.test.ts

@@ -0,0 +1,73 @@
+import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite'
+import process from 'node:process'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createDevToolsContext } from '../context'
+import '@vitejs/devtools-kit'
+
+function createConfig(plugins: Plugin[], command: 'serve' | 'build' = 'serve'): ResolvedConfig {
+  return {
+    root: process.cwd(),
+    command,
+    plugins,
+  } as unknown as ResolvedConfig
+}
+
+function createViteServer(): ViteDevServer {
+  return {
+    middlewares: {
+      use: vi.fn(),
+    },
+  } as unknown as ViteDevServer
+}
+
+/** A plugin whose dock names its client script by npm specifier, as the kit docs show. */
+function createBareSpecifierPlugin(): Plugin {
+  return {
+    name: 'test-bare-specifier-dock',
+    devtools: {
+      setup(ctx) {
+        ctx.docks.register({
+          id: 'test-bare-specifier',
+          title: 'Test',
+          icon: 'ph:bug-duotone',
+          type: 'action',
+          action: { importFrom: 'my-plugin/devtools-action' },
+        })
+      },
+    },
+  }
+}
+
+function spyOnDF8111() {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  return () => warn.mock.calls.filter(args => args.some(arg => String(arg).includes('DF8111'))).length
+}
+
+describe('createDevToolsContext client module resolution', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('declares the Vite `/@id/` resolver before plugin setup registers bare-specifier docks', async () => {
+    const countDF8111 = spyOnDF8111()
+
+    const ctx = await createDevToolsContext(
+      createConfig([createBareSpecifierPlugin()]),
+      createViteServer(),
+    )
+
+    expect(countDF8111()).toBe(0)
+    expect(ctx.staticConfig.dock?.clientModuleResolution).toBe('/@id/{specifier}')
+  })
+
+  it('keeps warning DF8111 without a dev server (standalone / build), where bare specifiers stay unresolvable', async () => {
+    const countDF8111 = spyOnDF8111()
+
+    const ctx = await createDevToolsContext(
+      createConfig([createBareSpecifierPlugin()], 'build'),
+    )
+
+    expect(ctx.staticConfig.dock?.clientModuleResolution).toBeUndefined()
+    expect(countDF8111()).toBe(1)
+  })
+})

packages/core/src/node/constants.ts

@@ -4,3 +4,10 @@ export const MARK_CHECK: string = c.green('✔')
 export const MARK_INFO: string = c.blue('ℹ')
 export const MARK_ERROR: string = c.red('✖')
 export const MARK_NODE: string = '⬢'
+
+/**
+ * Client-module resolution template declared when a live Vite dev server backs
+ * the requests: bare-specifier dock client scripts load through Vite's own
+ * `/@id/` resolution.
+ */
+export const DEVTOOLS_CLIENT_MODULE_RESOLUTION = '/@id/{specifier}'

packages/core/src/node/context.ts

@@ -6,6 +6,7 @@ import { createKitContext, createViteDevToolsHost } from '@vitejs/devtools-kit/n
 import { createDebug } from 'obug'
 import { DEVTOOLS_ASSETS_BASE, dirAssets } from '../dirs'
 import { getAuthHandler, isClientAuthDisabled } from './auth-handler'
+import { DEVTOOLS_CLIENT_MODULE_RESOLUTION } from './constants'
 import { diagnostics } from './diagnostics'
 import {
   defaultResolvedDevToolsConfig,
@@ -61,6 +62,18 @@ export async function createDevToolsContext(
   // setup() hooks can reference DTK codes via `ctx.diagnostics.logger`.
   context.diagnostics.register(diagnostics)
 
+  // Declare Vite's bare-specifier resolution before any dock registers. The hub
+  // checks for it inside `docks.register()`, so a plugin `setup()` hook naming
+  // an npm module in `importFrom` would otherwise warn DF8111 about a script
+  // that loads fine once `initHub` (in `createDevToolsHub`) declares the same
+  // template. Live dev server only — see `createDevToolsHub` for why.
+  if (viteServer) {
+    context.staticConfig.dock = {
+      ...context.staticConfig.dock,
+      clientModuleResolution: DEVTOOLS_CLIENT_MODULE_RESOLUTION,
+    }
+  }
+
   // The hub no longer synthesizes built-in docks — Vite DevTools, as the
   // high-level integration, registers the viewer's native views it wants. The
   // terminals + messages panels come from the official `@devframes/plugin-terminals`

packages/core/src/node/server.ts

@@ -6,6 +6,7 @@ import type { ViteDevToolsUiOptions } from './ui'
 import { initHub } from '@devframes/hub/initiate'
 import { DEVTOOLS_CONNECTION_META_FILENAME, DEVTOOLS_MOUNT_PATH } from '@vitejs/devtools-kit/constants'
 import { getAuthHandler, getBuildCapabilityToken, isBuildCapabilityAuth, isClientAuthDisabled } from './auth-handler'
+import { DEVTOOLS_CLIENT_MODULE_RESOLUTION } from './constants'
 import { resolveDockRendererRegistrations } from './renderers'
 import { getResolvedDevToolsConfig } from './resolved-config'
 import { createViteDevToolsUi } from './ui'
@@ -99,7 +100,9 @@ export async function createDevToolsHub(options: CreateDevToolsHubOptions): Prom
     // of Vite's transform pipeline. Standalone (CLI) and build snapshots have
     // no module graph to resolve against, so the template stays undeclared
     // there and such scripts must ship a self-contained bundle URL instead.
-    ...(context.viteServer ? { clientModuleResolution: '/@id/{specifier}' } : {}),
+    // `createDevToolsContext` already declares it ahead of the plugin setup
+    // hooks; repeating it here covers a context assembled elsewhere.
+    ...(context.viteServer ? { clientModuleResolution: DEVTOOLS_CLIENT_MODULE_RESOLUTION } : {}),
     auth: authDisabled ? false : getAuthHandler(context),
     ...(allowedOrigins ? { allowedOrigins } : {}),
     ...(mcp !== undefined ? { mcp } : {}),