vite-plugin-vue-inspector: clicking a Vue element to open its source file

The gap between a rendered element and the line that wrote it

Reading a broken layout in the browser usually means switching between two views of the same component: the pixels in the devtools window and the template text in your editor. A browser element picker tells you which node you selected and what classes and attributes it carries, but it stops there. You still have to search the project for the component name, then find the right branch of the template by eye. vite-plugin-vue-inspector closes that loop. As the README puts it, you jump from a Vue element in the browser to its source file in your editor.

The scope is narrow on purpose. The README states that this package is Vue 3 and Vite only, and the repository topics list Vue, Vite and debug tooling. There is no Vue 2 path described, no webpack loader, and no build-time analysis step. The audience is therefore developers working inside a Vite dev server on Vue 3 code, where hot reload and source maps are already part of the loop. If you are on Vue 2 or a webpack-based legacy app, nothing in this project addresses that setup.

The tool is a development aid rather than a runtime dependency. It registers dev-only markers on elements and draws an overlay, and none of that belongs in a production bundle.

Two lookup paths: Vite source maps first, DOM markers as fallback

The interesting design choice is that the plugin does not rely on a single mechanism. According to the README, it records source locations from Vue's compiled render output with Vite source maps. That path is the primary one because it uses data the compiler already produces, so a node that VNode instrumentation covered resolves to an exact file and location without any extra attribute written into the DOM.

The second path exists because that coverage is not complete. The README describes dev-only data-v-inspector DOM markers as a fallback for cases such as Vapor mode or nodes missed by VNode instrumentation. Vapor mode is named explicitly, which tells you the authors knew the compiled render output path would not describe every node in every renderer configuration. When the source map route returns nothing, the plugin falls back to a marker attribute placed on the element itself.

The consequence for a user is that highlight behaviour can vary between elements in the same page. A node produced under a renderer configuration the source map path does not cover still works, but through the other route, and the README does not document whether the two paths produce identical editor targets. Anyone depending on click to open as a primary navigation habit should check that behaviour against their own components, especially any that use Vapor mode.

Install and first click in a Vite project

The project is published as a dev dependency and expects a pnpm based workflow. The README gives one install line, and the repository's own package.json pins [email protected] with node >=22.12.0 as the engine floor, so an older Node runtime is outside what the maintainers test.

pnpm add -D vite-plugin-vue-inspector

The plugin then has to be listed in your Vite config alongside the Vue plugin. This is the exact configuration the README shows.

import Vue from '@vitejs/plugin-vue'
import Inspector from 'vite-plugin-vue-inspector'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [Vue(), Inspector()],
})

With the dev server running, the README gives the toggle as Command+Shift on macOS and Ctrl+Shift on Windows and Linux. Once the inspector is on, the page highlights elements and clicking a highlighted element opens the source location in your editor. The default hotkey combination is worth knowing before you install, because on both platforms Shift+Ctrl is also a common editor shortcut, and the README does not document a way to detect a conflict.

Nuxt needs the client loader appended to the entry module

Nuxt users do not simply add the plugin to a plugins array. The README tells you to use the Vite plugin directly and to append the client loader to Nuxt's entry module, and the appendTo option exists for exactly that. The configuration below is the one the README prints.

import Inspector from 'vite-plugin-vue-inspector'
import { defineNuxtConfig } from 'nuxt/config'

export default defineNuxtConfig({
  vite: {
    plugins: [
      Inspector({
        appendTo: /\/entry\.m?js$/,
      }),
    ],
  },
})

The regular expression matches the entry module name, with an optional m before js to allow the .mjs variant. The practical consequence is that Nuxt support is not a preset you can enable. It is a wiring step you own, and the README does not explain what happens when the pattern fails to match, for example under a different Nuxt output layout. If the overlay never appears in a Nuxt app, the appendTo pattern is the first thing to check.

The repository keeps two playground projects, packages/playground/vue and packages/playground/nuxt, runnable through the scripts in the root package.json, so both paths have a reference setup inside the project itself.

The option set is small and mostly about overlay behaviour

Everything the plugin exposes is collected in a single options interface, and it is worth reading as a whole because the entries are narrow in purpose.

interface VitePluginInspectorOptions {
  enabled?: boolean
  toggleComboKey?: string | false
  toggleButtonVisibility?: 'always' | 'active' | 'never'
  toggleButtonPos?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
  appendTo?: string | RegExp
  lazyLoad?: number | false
  disableInspectorOnEditorOpen?: boolean
  launchEditor?: string
  reduceMotion?: boolean
  viteDevtools?: boolean
}

Three of these decide how the overlay appears. toggleButtonVisibility can always, active or never, and toggleButtonPos pins the button to one of four corners. toggleComboKey accepts a string or false, so the keyboard shortcut can be replaced or removed entirely, which is the answer to the Shift+Ctrl collision described earlier.

Two options touch the editor side. disableInspectorOnEditorOpen closes the inspector after a successful jump, which keeps the page clean when you click through several elements in a row. launchEditor takes a string, presumably the command used to open a file, but the README does not list which editor commands are supported or how to point it at an editor that is not on the machine's path.

reduceMotion and lazyLoad round out the list. lazyLoad takes a number or false, which reads as a delay before the client code loads, while reduceMotion turns off animated transitions in the overlay.

The overlay is DOM and SVG rather than a Vue component

The README notes that the browser overlay is drawn by client/overlay with DOM and SVG APIs instead of a Vue SFC. That is a deliberate trade-off. A Vue component overlay would inherit the app's own reactivity and rendering pipeline, which is exactly the thing you are trying to inspect and which can fail when the app itself is broken. Drawing with plain DOM and SVG APIs keeps the tool independent of the application under inspection.

The same choice shapes how the overlay is loaded. The README shows it being pulled in lazily inside a hot context, guarded so it only exists during development.

if (import.meta.hot) import('vite-plugin-vue-inspector/client/overlay')

The import.meta.hot guard is the piece that keeps the overlay out of a production build, and the README pairs it with the lazyLoad option for the timing of that import.

The plugin also registers itself as a Vite DevTools dock action through @vitejs/devtools-kit. The README states that this integration is enabled by default and shows the explicit option form.

Inspector({
  viteDevtools: true,
})

When the dock action is activated, the inspector is enabled and editor opening goes through the Vite DevTools RPC. That is a real difference in approach against a standalone workflow: instead of a hotkey and a corner button, you enter the inspector from the Vite DevTools panel and the file opening is routed over the DevTools RPC channel rather than handled by the plugin alone.

A window object and headless listeners for scripted checks

The overlay exposes a browser control object on the window, which is the cheapest way to script the inspector in a devtools console or an end to end test.

window.__VUE_INSPECTOR__?.enable()
window.__VUE_INSPECTOR__?.disable()
window.__VUE_INSPECTOR__?.toggleEnabled()

The optional chaining matters if you call these in a context where the overlay never loaded, since the object is simply absent outside development.

For more selective work, the README lists headless helpers from the client/listeners entry, described as available without the built-in overlay.

import {
  events,
  findTraceAtPointer,
  findTraceFromElement,
} from 'vite-plugin-vue-inspector/client/listeners'

The exported names suggest the intended use. findTraceFromElement resolves the trace for a known element and findTraceAtPointer does it for whatever sits under a pointer position, which is the mechanism behind the click to open behaviour in a form you can drive yourself. events is exposed for listening to those lookups. The README gives no signatures, no return shapes and no event names for this module, so if you plan to build on it you will be reading the shipped types rather than the documentation.

One limit worth stating plainly: the helpers locate a source location for a node, they do not assert on application behaviour. There is no documented way to make the inspector fail a build, so this is a developer convenience rather than a testable contract.

Maintenance state, licence, and where the tool stops

The repository is not archived, and the last push was on 2026-06-08, the same day as the v7.0.0 release. Earlier tags in the release history sit at 5.0.0 on 2024-04-14 and 5.2.0 on 2024-09-02, so the version numbering jumped between 5.x and 7.x without a 6.x entry appearing in that list, which suggests the major version was tied to a compatibility change rather than a slow release cadence. The project is MIT licensed, and the licence covers the package as published; that carries no obligation on the code you debug with it.

Two boundaries are worth keeping in mind. First, this is a Vue 3 and Vite only tool with no documented Vue 2 or webpack path. Second, the editor integration depends on a launch command running on the machine, and the README does not document the list of editor commands that are known to work, so an unusual editor setup is where you will meet friction first.

Compared with the browser's own element picker, the difference in approach is that the picker stops at the node and this plugin resolves the node back to a source location, which requires Vite source maps and the plugin's own instrumentation. Compared with a plain search in your editor, it removes the manual step of finding which component and which branch of the template produced a node. Neither comparison removes the fallback caveat: some nodes are located through a DOM marker rather than the source map path.

Editorial conclusion

Use vite-plugin-vue-inspector if your day is spent in Vue 3 single file components under Vite and you want a click in the browser to land on the right template line, and expect to add the appendTo loader yourself on Nuxt. Skip it if you need Vue 2 support, a headless build-time check, or a guarantee that the highlight covers every node, since the DOM marker path is a fallback for cases VNode instrumentation misses. Before adopting, check the one thing the README leaves open in your own project: verify that pressing the toggle key opens your editor on the machines and shells your team actually uses, since the launchEditor option is only a string with no documented list of supported values.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. webfansplz/vite-plugin-vue-inspector on GitHub