@lirankor/vite-plugin-component-tagger

A Vite plugin that adds data attributes to JSX/TSX and Vue SFC elements for debugging and development purposes. This plugin helps developers identify which components and files generated specific DOM elements in the browser's developer tools.

Features

• Tags both HTML elements and components - Works with <div>, <Button>, <Stack>, <q-page>, <q-btn>, etc.
• Vue SFC support - Scoped to <template> blocks only; <script> and <style> are never touched
• Kebab-case component matching - Fully supports kebab-case components like <q-page>, <q-btn>, <my-component>
• Precise line number tracking - Shows exact source line where element is defined
• Self-closing tag support - Handles <Component /> syntax correctly
• TypeScript-aware - Avoids breaking TypeScript generic syntax
• Optimized performance - Only runs during development when explicitly enabled
• Clean console output - Minimal, informative logging

Installation

npm install @lirankor/vite-plugin-component-tagger --save-dev

Usage

React / Vite

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { componentTagger } from '@lirankor/vite-plugin-component-tagger'

export default defineConfig({
  plugins: [
    componentTagger({
      enabled: process.env.NODE_ENV === 'development'
    }),
    react(),
  ],
})

Vue / Nuxt

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { componentTagger } from '@lirankor/vite-plugin-component-tagger'

export default defineConfig({
  plugins: [
    componentTagger({
      enabled: process.env.NODE_ENV === 'development'
    }),
    vue(),
  ],
})

Quasar (with @quasar/app-vite)

In your quasar.config.js (or .ts):

import { componentTagger } from '@lirankor/vite-plugin-component-tagger'

export default defineConfig((ctx) => ({
  build: {
    vitePlugins: [
      ['@lirankor/vite-plugin-component-tagger', [{ enabled: ctx.dev }]]
    ]
  }
}))

Or using the extendViteConf hook:

import { componentTagger } from '@lirankor/vite-plugin-component-tagger'

export default defineConfig((ctx) => ({
  build: {
    extendViteConf(viteConf) {
      if (ctx.dev) {
        viteConf.plugins?.push(componentTagger({ enabled: true }))
      }
    }
  }
}))

Kebab-case components like <q-page>, <q-btn>, <q-card>, and any custom kebab-case component such as <my-component> or <carousel-component> are fully supported.

Conditional Usage (Recommended)

For maximum control, create a separate npm script:

package.json:

{
  "scripts": {
    "dev": "vite",
    "dev:debug": "ENABLE_COMPONENT_TAGGER=true vite"
  }
}

vite.config.js:

import { componentTagger } from '@lirankor/vite-plugin-component-tagger'

export default defineConfig({
  plugins: [
    componentTagger({
      enabled: process.env.ENABLE_COMPONENT_TAGGER === 'true'
    }),
    react(), // or vue()
  ],
})

Then run with component tagging:

npm run dev:debug

Generated Attributes

The plugin adds three data attributes to each element:

• data-dev-component: The component file name (without extension)
• data-dev-file: Full file path with line number
• data-dev-tag: The HTML/component element tag name

Example Output (React)

Source code (Button.jsx:15):

export function Button({ children }) {
  return <button className="btn">{children}</button>
}

Generated HTML:

<button 
  class="btn" 
  data-dev-component="Button" 
  data-dev-file="/src/components/Button.jsx:15" 
  data-dev-tag="button"
>
  Click me
</button>

Example Output (Vue)

Source code (MyPage.vue):

<template>
  <q-page>
    <q-btn label="Click me" />
  </q-page>
</template>

Generated template:

<q-page data-dev-component="MyPage" data-dev-file="/src/pages/MyPage.vue:2" data-dev-tag="q-page">
  <q-btn label="Click me" data-dev-component="MyPage" data-dev-file="/src/pages/MyPage.vue:3" data-dev-tag="q-btn" />
</q-page>

Configuration

Options

interface ComponentTaggerOptions {
  enabled?: boolean; // Default: true
}

Advanced Configuration

componentTagger({
  enabled: process.env.NODE_ENV === 'development' && process.env.DEBUG_COMPONENTS === 'true'
})

Use Cases

1. Component Debugging

Quickly identify which component generated a specific DOM element:

// In browser console
const element = document.querySelector('.some-class')
console.log(element.dataset.devComponent) // "UserProfile"
console.log(element.dataset.devFile)      // "/src/components/UserProfile.jsx:42"

2. Visual Testing

Perfect for visual regression testing and component identification in automated tests.

3. Code Reviews

Help reviewers understand the relationship between DOM structure and source code.

Important Notes

• Development only: This plugin should only be enabled during development
• Build size: Has zero impact on production builds when disabled
• Performance: Minimal overhead - only processes JSX/TSX/Vue files
• Syntax safety: Carefully avoids breaking TypeScript generics and complex JSX
• Vue scoping: Only the <template> block is processed; <script> and <style> are never modified

Debugging

The plugin provides helpful console output:

Component Tagger: Tagged 156 elements across 23 files

Requirements

• Vite 4.0.0 or higher
• TypeScript/JavaScript project with JSX/TSX or Vue SFC files

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Related

• Vite Plugin Documentation
• React Developer Tools
• Vue Devtools

Made for the React & Vue / Vite community