Vite Plugin Vue Tracer

Common errors

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

  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.
  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

  cause 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"

  cause 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

  cause 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()`.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.
• breaking 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.
  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.

Install

• npm install vite-plugin-vue-tracer npm
• yarn add vite-plugin-vue-tracer yarn
• pnpm add vite-plugin-vue-tracer pnpm

Imports

• VueTracer
  wrong:

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

  correct:

  import { VueTracer } from '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.

Quickstart

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
    })
  })
}