npm package: @lirankor/vite-plugin-component-tagger
Description: A Vite plugin that adds data attributes to JSX/TSX and Vue SFC elements for debugging and development purposes
Author: Liran Koren
Latest version: 1.2.0

# @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

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

## Usage

### React / Vite

```javascript
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

```javascript
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`):

```javascript
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:

```javascript
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:**
```json
{
  "scripts": {
    "dev": "vite",
    "dev:debug": "ENABLE_COMPONENT_TAGGER=true vite"
  }
}
```

**vite.config.js:**
```javascript
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:
```bash
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):**
```jsx
export function Button({ children }) {
  return <button className="btn">{children}</button>
}
```

**Generated HTML:**
```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):**
```vue
<template>
  <q-page>
    <q-btn label="Click me" />
  </q-page>
</template>
```

**Generated template:**
```html
<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

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

### Advanced Configuration

```javascript
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:

```javascript
// 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](LICENSE) file for details.

## Related

- [Vite Plugin Documentation](https://vitejs.dev/guide/api-plugin.html)
- [React Developer Tools](https://github.com/facebook/react/tree/main/packages/react-devtools)
- [Vue Devtools](https://devtools.vuejs.org/)

---

Made for the React & Vue / Vite community