{"id":12381,"library":"vite-plugin-vue-tracer","title":"Vite Plugin Vue Tracer","description":"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.","status":"active","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/antfu/vite-plugin-vue-tracer","tags":["javascript","vue","vite-plugin","devtools","typescript"],"install":[{"cmd":"npm install vite-plugin-vue-tracer","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-vue-tracer","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-vue-tracer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the Vite plugin itself.","package":"vite","optional":false},{"reason":"Peer dependency for tracing Vue components and VDOM.","package":"vue","optional":false}],"imports":[{"note":"Used in `vite.config.ts`. The package is ESM-only; CommonJS `require` will fail.","wrong":"const VueTracer = require('vite-plugin-vue-tracer')","symbol":"VueTracer","correct":"import { VueTracer } from 'vite-plugin-vue-tracer'"},{"note":"Client-side imports for the built-in overlay functionality. Typically wrapped in `if (import.meta.hot)` for development.","symbol":"{ events, state }","correct":"import { events, state } from 'vite-plugin-vue-tracer/client/overlay'"},{"note":"Client-side imports for headless tracing APIs. Useful for custom inspector UIs. The 'record' entry is usually auto-injected by the plugin.","symbol":"{ findTraceFromElement }","correct":"import { findTraceFromElement } from 'vite-plugin-vue-tracer/client/record'"}],"quickstart":{"code":"import { defineConfig } from 'vite'\nimport { VueTracer } from 'vite-plugin-vue-tracer'\n\nexport default defineConfig({\n  plugins: [\n    VueTracer(),\n  ],\n})\n\n// In your main client-side entry file (e.g., main.ts)\n// Only apply in development and if HMR is active\nif (import.meta.hot) {\n  import('vite-plugin-vue-tracer/client/overlay').then(({ events, state }) => {\n    // Enable the visual overlay\n    state.isEnabled = true\n\n    events.on('hover', (info) => {\n      console.log('Hovered:', info.filepath, info.line, info.column)\n    })\n\n    events.on('click', (info) => {\n      console.log('Clicked:', info.filepath, info.line, info.column)\n      // Example: Open in VS Code (requires custom setup for 'openInEditor')\n      // openInEditor(`${info.filepath}:${info.line}:${info.column}`)\n      state.isEnabled = false // Disable overlay after click for single use\n    })\n  })\n}","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"Client-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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"As 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.","severity":"breaking","affected_versions":">=1.1.2"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'events') at main.ts"},{"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.","cause":"Your project's Vite version does not meet the peer dependency requirements of the plugin.","error":"Error: vite-plugin-vue-tracer requires vite@^6.0.0 || ^7.0.0 but got vite@5.x.x"},{"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`.","cause":"The `vite-plugin-vue-tracer` package is not correctly installed or resolvable in your project.","error":"Error: [vite] Internal server error: Failed to resolve import \"vite-plugin-vue-tracer\" from \"vite.config.ts\""},{"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()`.","cause":"Attempting to use `VueTracer` as a default export or an incorrectly destructured named export.","error":"TypeError: VueTracer is not a function"}],"ecosystem":"npm"}