feat(core): introduce @vitejs/devtools/preamble for explicit devtools client injection

Author: webfansplz

docs/guide/index.md

@@ -110,6 +110,18 @@ pnpm dev
 
 Then open your app in the browser and open the DevTools panel.
 
+#### Projects without an HTML entry
+
+The embedded DevTools client is usually injected through Vite's `transformIndexHtml` hook. If your app does not start from an HTML entry, keep the `DevTools()` plugin enabled and import the preamble manually in your client entry instead:
+
+```ts twoslash
+import '@vitejs/devtools/preamble'
+```
+
+This loads the same DevTools client that would normally be added to `index.html`. Put it in a browser entry such as `main.ts` or `entry.client.ts`, not in server-only files or shared SSR entry files.
+
+If your project does have an HTML entry, avoid importing the preamble in addition to the HTML injection, as that would inject the client twice and create duplicate dock elements.
+
 #### Building with the App
 
 You can also generate a static DevTools build alongside your app's build output by enabling the `build.withApp` option:

packages/core/package.json

@@ -28,15 +28,17 @@
     "./config": "./dist/config.js",
     "./dirs": "./dist/dirs.js",
     "./internal": "./dist/internal.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./preamble": "./types/preamble.d.ts"
   },
   "types": "./dist/index.d.ts",
   "bin": {
     "vite-devtools": "./bin.js"
   },
   "files": [
     "bin.js",
-    "dist"
+    "dist",
+    "types"
   ],
   "scripts": {
     "build": "pnpm build:js && pnpm build:standalone",
@@ -55,6 +57,7 @@
     "vite": "*"
   },
   "dependencies": {
+    "@rolldown/pluginutils": "catalog:deps",
     "@vitejs/devtools-kit": "workspace:*",
     "@vitejs/devtools-rolldown": "workspace:*",
     "@vitejs/devtools-rpc": "workspace:*",

packages/core/src/node/plugins/index.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from 'vite'
 import { DevToolsBuild } from './build'
 import { DevToolsInjection } from './injection'
+import { DevToolsPreamble } from './preamble'
 import { DevToolsServer } from './server'
 
 export interface DevToolsOptions {
@@ -38,6 +39,7 @@ export async function DevTools(options: DevToolsOptions = {}): Promise<Plugin[]>
   const plugins = [
     DevToolsInjection(),
     DevToolsServer(),
+    DevToolsPreamble({ name: '@vitejs/devtools/preamble' }),
   ]
 
   if (build?.withApp) {

packages/core/src/node/plugins/injection.ts

@@ -3,19 +3,26 @@ import process from 'node:process'
 import { join, normalize } from 'pathe'
 import { dirDist } from '../../dirs'
 
+export function getClientInjectUrl() {
+  const fileUrl = process.env.VITE_DEVTOOLS_LOCAL_DEV
+    ? normalize(join(dirDist, '..', 'src/client/inject/index.ts'))
+    : normalize(join(dirDist, 'client/inject.js'))
+
+  return `/@fs/${fileUrl}`
+}
+
 export function DevToolsInjection(): Plugin {
   return {
     name: 'vite:devtools:injection',
     enforce: 'post',
+    apply: 'serve',
     transformIndexHtml() {
-      const fileUrl = process.env.VITE_DEVTOOLS_LOCAL_DEV
-        ? normalize(join(dirDist, '..', 'src/client/inject/index.ts'))
-        : normalize(join(dirDist, 'client/inject.js'))
+      const fileUrl = getClientInjectUrl()
       return [
         {
           tag: 'script',
           attrs: {
-            src: `/@fs/${fileUrl}`,
+            src: fileUrl,
             type: 'module',
           },
           injectTo: 'body',

packages/core/src/node/plugins/preamble.ts

@@ -0,0 +1,27 @@
+import type { Plugin } from 'vite'
+import { exactRegex } from '@rolldown/pluginutils'
+import { getClientInjectUrl } from './injection'
+
+export function DevToolsPreamble({ name }: { name: string }): Plugin {
+  return {
+    name: 'vite:devtools:preamble',
+    apply: 'serve',
+    resolveId: {
+      order: 'pre',
+      filter: { id: exactRegex(name) },
+      handler(source) {
+        if (source === name) {
+          return `\0${source}`
+        }
+      },
+    },
+    load: {
+      filter: { id: exactRegex(`\0${name}`) },
+      handler(id) {
+        if (id === `\0${name}`) {
+          return `import ${JSON.stringify(getClientInjectUrl())}`
+        }
+      },
+    },
+  }
+}

packages/core/tsdown.config.ts

@@ -8,7 +8,11 @@ const define = {
 }
 
 export default defineConfig({
-  exports: true,
+  exports: {
+    customExports: {
+      './preamble': './types/preamble.d.ts',
+    },
+  },
   plugins: [
     Vue({
       isProduction: true,

packages/core/types/preamble.d.ts

@@ -0,0 +1 @@
+export {}

pnpm-lock.yaml

@@ -52,6 +52,7 @@ catalogs:
   deps:
     '@pnpm/read-project-manifest': ^1001.2.5
     '@rolldown/debug': ^1.0.0-rc.11
+    '@rolldown/pluginutils': ^1.0.0-rc.11
     ansis: ^4.2.0
     birpc: ^4.0.0
     cac: ^7.0.0