feat(devtools): make vite-plugin-inspect an optional peer dependency (#1055)

Author: antfubot

docs/content/1.guide/1.features.md

@@ -161,6 +161,8 @@ Virtual Files tab shows the virtual files generated by Nuxt to support the conve
 
 Inspect expose the [`vite-plugin-inspect`](https://github.com/antfu/vite-plugin-inspect) integration, allowing you to inspect transformation steps of Vite.
 
+`vite-plugin-inspect` is an optional peer dependency, so it is not installed by default. Until you add it to your project, DevTools shows an install launcher in the Inspect slot (the same experience as Vite Plus DevTools) — click it to install the plugin and restart the dev server to activate the view.
+
 <img width="1284" src="https://user-images.githubusercontent.com/11247099/217670818-77f91135-7318-462e-9148-4ad504c82555.png" alt="Nuxt DevTools Inspect tab">
 
 ## Settings

packages/devtools-kit/src/_types/options.ts

@@ -43,7 +43,12 @@ export interface ModuleOptions {
   vueDevTools?: boolean
 
   /**
-   * Enable vite-plugin-inspect
+   * Enable the Vite Inspect integration.
+   *
+   * `vite-plugin-inspect` is an optional peer dependency. When it isn't
+   * installed, DevTools shows an install launcher in its place (like Vite Plus
+   * DevTools); once installed, the real Inspect view is mounted. Set this to
+   * `false` to disable the integration (and its launcher) entirely.
    *
    * @default true
    */

packages/devtools/package.json

@@ -45,14 +45,18 @@
   "peerDependencies": {
     "nitro": "^3.0.0-0",
     "nitropack": "^2.0.0",
-    "vite": "^8.1.5"
+    "vite": "^8.1.5",
+    "vite-plugin-inspect": "catalog:prod"
   },
   "peerDependenciesMeta": {
     "nitro": {
       "optional": true
     },
     "nitropack": {
       "optional": true
+    },
+    "vite-plugin-inspect": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -85,7 +89,6 @@
     "tinyglobby": "catalog:prod",
     "unstorage": "catalog:prod",
     "verkit": "catalog:prod",
-    "vite-plugin-inspect": "catalog:prod",
     "vite-plugin-vue-tracer": "catalog:prod",
     "ws": "catalog:prod"
   },
@@ -136,6 +139,7 @@
     "vanilla-jsoneditor": "catalog:frontend",
     "vis-data": "catalog:frontend",
     "vis-network": "catalog:frontend",
+    "vite-plugin-inspect": "catalog:prod",
     "vue-tsc": "catalog:cli",
     "vue-virtual-scroller": "catalog:frontend"
   }

packages/devtools/src/integrations/analyze-build.ts

@@ -3,10 +3,12 @@ import type { AnalyzeBuildMeta, ModuleOptions } from '../types'
 import { addVitePlugin } from '@nuxt/kit'
 import { join } from 'pathe'
 import { getFolderSize } from '../utils/fs'
-import { createVitePluginInspect } from './vite-inspect'
+import { createVitePluginInspect, isVitePluginInspectAvailable } from './vite-inspect'
 
 export async function setup(nuxt: Nuxt, options: ModuleOptions) {
-  if (options.viteInspect !== false) {
+  // Only wire the Vite Inspect build report when the optional
+  // `vite-plugin-inspect` peer dependency is actually installed.
+  if (options.viteInspect !== false && isVitePluginInspectAvailable(nuxt.options.rootDir)) {
     addVitePlugin(
       await createVitePluginInspect({
         build: true,

packages/devtools/src/integrations/vite-inspect.ts

@@ -3,16 +3,49 @@ import type { ViteInspectOptions } from 'vite-plugin-inspect'
 import type { NuxtDevtoolsServerContext, ServerFunctions } from '../types'
 import { onDevtoolsReady } from '@nuxt/devtools-kit'
 import { addVitePlugin, logger } from '@nuxt/kit'
+import { createInstallLauncher } from '@vitejs/devtools-kit/node'
+import { isPackageExists } from 'local-pkg'
 import { RPC_NAMESPACE } from '../rpc-namespace'
 
 const VERSION_QUERY_RE = /\?v=\w+$/
 const VUE_EXT_RE = /\.vue($|\?v=)/
 
+// `vite-plugin-inspect` registers its own dock under this id/title/icon. The
+// install launcher we mount when the package is absent reuses them so the rail
+// slot stays stable before and after the user installs it.
+const INSPECT_DOCK_ID = 'vite-plugin-inspect'
+const INSPECT_DOCK_TITLE = 'Inspect'
+const INSPECT_DOCK_ICON = 'ph:magnifying-glass-duotone'
+
+/**
+ * Whether the optional `vite-plugin-inspect` peer dependency is installed in
+ * the user's project.
+ */
+export function isVitePluginInspectAvailable(rootDir: string): boolean {
+  return isPackageExists('vite-plugin-inspect', { paths: [rootDir] })
+}
+
 export async function createVitePluginInspect(options?: ViteInspectOptions): Promise<Plugin> {
   return await import('vite-plugin-inspect').then(r => r.default(options))
 }
 
 export async function setup(ctx: NuxtDevtoolsServerContext) {
+  // `vite-plugin-inspect` is an optional peer dependency. When the user hasn't
+  // installed it, mount a discovery/install launcher in its dock slot (the same
+  // UX as Vite Plus DevTools' built-in integration launchers) instead of the
+  // real Inspect view. Clicking it installs the package as a tracked terminal
+  // session, then asks for a dev-server restart to activate the real plugin.
+  if (!isVitePluginInspectAvailable(ctx.nuxt.options.rootDir)) {
+    addVitePlugin(createInstallLauncher({
+      id: INSPECT_DOCK_ID,
+      title: INSPECT_DOCK_TITLE,
+      icon: INSPECT_DOCK_ICON,
+      label: 'Vite Inspect',
+      install: ['vite-plugin-inspect'],
+    }))
+    return
+  }
+
   const plugin = await createVitePluginInspect()
   addVitePlugin(plugin)