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 client injector manually in your client entry instead:
+
+```ts twoslash
+import '@vitejs/devtools/client/inject'
+```
+
+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 `@vitejs/devtools/client/inject` 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

@@ -55,6 +55,7 @@
     "vite": "*"
   },
   "dependencies": {
+    "@rolldown/pluginutils": "catalog:deps",
     "@vitejs/devtools-kit": "workspace:*",
     "@vitejs/devtools-rolldown": "workspace:*",
     "@vitejs/devtools-rpc": "workspace:*",

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/tsdown.config.ts

@@ -8,7 +8,6 @@ const define = {
 }
 
 export default defineConfig({
-  exports: true,
   plugins: [
     Vue({
       isProduction: true,

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