Component Tagger

A Vite plugin that automatically adds data-component-id attributes to JSX/TSX components for easier debugging and testing.

Features

- 🏷️ Automatically adds component IDs to JSX elements
- 📁 Configurable file path inclusion (filename or full path)
- 🔢 Optional line number inclusion
- 🎯 Smart component detection (uppercase = components, lowercase = DOM elements)
- ⚡ Development-only by default - no production overhead
- 🔧 Customizable ID generation
- 📝 TypeScript support

Installation

``bash
npm install --save-dev component-tagger
`

Setup

After installation, you need to configure the plugin in your Vite config:

`bash
npx component-tagger-setup
`

This will automatically add the plugin to your vite.config.ts file.

Usage

$3

After running npx component-tagger-setup, your vite.config.ts will look like this:

`typescript
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { componentTagger } from 'component-tagger'

export default defineConfig({
plugins: [
react(),
componentTagger() // Default settings: path, line, file (development only)
]
})
`

$3

`typescript
import { componentTagger } from 'component-tagger'

export default defineConfig({
plugins: [
react(),
componentTagger({
includeId: true, // data-component-id="src/Button.tsx:15:4"
includeName: false, // data-component-name="Button"
includePath: true, // data-component-path="src/Button.tsx"
includeLine: true, // data-component-line="15"
includeFile: true, // data-component-file="Button.tsx"
includeContent: false, // data-component-content="%7B...%7D"
developmentOnly: true // Only in development
})
]
})
`

Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| includeId | boolean | true | Component ID (file:line:column) |
| includeName | boolean | false | Element name (div, Button, etc.) |
| includePath | boolean | true | File path |
| includeLine | boolean | true | Line number |
| includeFile | boolean | true | Filename |
| includeContent | boolean | false | Props and content as JSON |
| developmentOnly | boolean | true | Only add in development |

What It Does

The plugin adds customizable data attributes to JSX elements. By default, it adds attributes only in development mode (not in production builds):

- data-component-id: File path with line and column (e.g., src/components/Button.tsx:15:4)
- data-component-path: Full file path
- data-component-line: Line number
- data-component-file: Filename

Examples

$3

`tsx
function MyComponent() {
return (



)
}
`

$3

`tsx
function MyComponent() {
return (



)
}
`

$3

`tsx
// componentTagger({ includeId: true, includeName: true, includePath: true, includeLine: true, includeFile: true, includeContent: true })

data-component-id="src/MyComponent.tsx:6:8"
data-component-name="Button"
data-component-path="src/MyComponent.tsx"
data-component-line="6"
data-component-file="MyComponent.tsx"
data-component-content="%7B%22onClick%22%3A%22%5Bexpression%5D%22%2C%22text%22%3A%22Click%20me%22%7D"
onClick={handleClick}
>
Click me

`

Uninstalling

When you're ready to remove Component Tagger, you need to run two commands:

1. Remove from Vite config:
`bash
npx component-tagger-cleanup
`

2. Uninstall the package:
`bash
npm uninstall component-tagger
`

The cleanup command will:
- ✅ Remove the plugin from your vite.config.ts
- ✅ Remove the import statement
- ✅ Clean up your configuration

Use Cases

- Debugging: Easily identify components in browser dev tools
- Testing: Use component IDs for reliable E2E test selectors
- Development: Quick component identification during development
- Documentation: Generate component documentation with file references

Notes

- Development only by default - won't add attributes in production builds
- Only processes components (uppercase JSX elements), not DOM elements (lowercase)
- Skips JSX fragments as they don't render as DOM elements
- Automatically handles existing attributes to avoid duplicates
- Works with TypeScript and modern JSX syntax
- Supports complex component names (e.g., React.Component, styled.div`)

License

MIT