Registry / web-framework / vite-plugin-vue-tracer

vite-plugin-vue-tracer

library1.3.0jsnpmunverified

vite-plugin-vue-tracer is a development-only Vite plugin designed to trace the source code location of elements and Virtual DOM nodes within Vue Single-File Components (SFCs). It serves as a modern replacement for `vite-plugin-vue-inspector`, leveraging Vite's internal source map capabilities to resolve source locations without injecting additional data attributes into the DOM. This approach aims for cleaner DOM and improved performance. The current stable version is `1.3.0`. The project maintains an active release cadence, frequently updating to support the latest versions of Vite and Vue DevTools. It differentiates itself by offering both a built-in overlay UI and headless APIs, allowing developers to build custom inspection tools or integrate tracing functionality more deeply into their development workflow.

web-framework testing

npm install vite-plugin-vue-tracer

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-VUE-TR

vite-plugin-vue-tracer

web-frameworkjavascriptv1.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueTracer

✓ import { VueTracer } from 'vite-plugin-vue-tracer'

✗ const VueTracer = require('vite-plugin-vue-tracer')

Used in `vite.config.ts`. The package is ESM-only; CommonJS `require` will fail.

{ events, state }

✓ import { events, state } from 'vite-plugin-vue-tracer/client/overlay'

Client-side imports for the built-in overlay functionality. Typically wrapped in `if (import.meta.hot)` for development.

{ findTraceFromElement }

✓ import { findTraceFromElement } from 'vite-plugin-vue-tracer/client/record'

Client-side imports for headless tracing APIs. Useful for custom inspector UIs. The 'record' entry is usually auto-injected by the plugin.

This quickstart demonstrates how to integrate `vite-plugin-vue-tracer` into a Vite project, enabling the built-in development overlay and listening for hover and click events to trace Vue component source locations. It shows both plugin configuration and client-side integration.

import { defineConfig } from 'vite' import { VueTracer } from 'vite-plugin-vue-tracer' export default defineConfig({ plugins: [ VueTracer(), ], }) // In your main client-side entry file (e.g., main.ts) // Only apply in development and if HMR is active if (import.meta.hot) { import('vite-plugin-vue-tracer/client/overlay').then(({ events, state }) => { // Enable the visual overlay state.isEnabled = true events.on('hover', (info) => { console.log('Hovered:', info.filepath, info.line, info.column) }) events.on('click', (info) => { console.log('Clicked:', info.filepath, info.line, info.column) // Example: Open in VS Code (requires custom setup for 'openInEditor') // openInEditor(`${info.filepath}:${info.line}:${info.column}`) state.isEnabled = false // Disable overlay after click for single use }) }) }

Debug

Known issues

breakingThe plugin's integration with Vite DevTools has undergone multiple iterations and API changes. Older configurations for DevTools integration might cease to function or behave unexpectedly with newer plugin versions.

fix

Always refer to the latest README and changelog for the correct configuration when integrating with Vite DevTools. Ensure your `vite` and `@vitejs/devtools-kit` versions are compatible with the plugin version.

affects: >=1.1.0

gotchaClient-side components like `vite-plugin-vue-tracer/client/overlay` and `/client/record` are intended for development environments only and rely on Vite's HMR (`import.meta.hot`). Including them in production builds without conditional checks can lead to errors or unnecessary bundle size.

fix

Always wrap client-side imports and logic with `if (import.meta.hot)` to ensure they are only active during development and are tree-shaken from production builds.

affects: >=1.0.0

breakingAs of v1.1.2, Vite DevTools integration was disabled by default. If you were relying on this integration, you might find it no longer active.

fix

Explicitly enable Vite DevTools integration if needed by consulting the latest plugin configuration options, or utilize the headless client APIs to build custom integrations.

affects: >=1.1.2

breakingThe plugin has peer dependencies on `vite` (`^6.0.0 || ^7.0.0`) and `vue` (`^3.5.0`). Mismatched versions can lead to build failures or runtime errors.

fix

Ensure your project's `vite` and `vue` versions satisfy the declared peer dependency ranges for `vite-plugin-vue-tracer`. Upgrade or downgrade dependencies as necessary.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'events') at main.ts

Attempting to access client-side `events` or `state` before the `vite-plugin-vue-tracer/client/overlay` module has been fully loaded, or when `import.meta.hot` is false in a non-development environment.

fix

Ensure the client-side import is properly asynchronous (`.then()`) and strictly guarded by `if (import.meta.hot)` to ensure the module is only loaded and executed when HMR is active in development.

Error: vite-plugin-vue-tracer requires vite@^6.0.0 || ^7.0.0 but got vite@5.x.x

Your project's Vite version does not meet the peer dependency requirements of the plugin.

fix

Upgrade your project's `vite` dependency to a compatible version (6.x or 7.x) using `npm install vite@latest` or `yarn add vite@latest` and verify it matches the required range.

Error: [vite] Internal server error: Failed to resolve import "vite-plugin-vue-tracer" from "vite.config.ts"

The `vite-plugin-vue-tracer` package is not correctly installed or resolvable in your project.

fix

Run `npm install -D vite-plugin-vue-tracer` or `yarn add -D vite-plugin-vue-tracer` to ensure the package is installed. Verify the import path in `vite.config.ts`.

TypeError: VueTracer is not a function

Attempting to use `VueTracer` as a default export or an incorrectly destructured named export.

fix

Ensure `VueTracer` is imported as a named export: `import { VueTracer } from 'vite-plugin-vue-tracer'`. Also verify it's correctly called as a function: `VueTracer()`.

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

viterequiredPeer dependency for the Vite plugin itself.

vuerequiredPeer dependency for tracing Vue components and VDOM.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/antfu/vite-plugin-vue-tracer ↗

packagehttps://www.npmjs.com/package/vite-plugin-vue-tracer ↗