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

npm install --save-dev component-tagger

Setup

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

npx component-tagger-setup

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

Usage

Basic Setup

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

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

Custom Configuration

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

Before Transformation

function MyComponent() {
  return (
    <div>
      <Header title="Hello World" />
      <MainContent>
        <Button onClick={handleClick}>Click me</Button>
      </MainContent>
    </div>
  )
}

After Transformation (Default Settings)

function MyComponent() {
  return (
    <div>
      <Header 
        data-component-id="src/MyComponent.tsx:4:6"
        data-component-path="src/MyComponent.tsx"
        data-component-line="4"
        data-component-file="MyComponent.tsx"
        title="Hello World" 
      />
      <MainContent 
        data-component-id="src/MyComponent.tsx:5:6"
        data-component-path="src/MyComponent.tsx"
        data-component-line="5"
        data-component-file="MyComponent.tsx"
      >
        <Button 
          data-component-id="src/MyComponent.tsx:6:8"
          data-component-path="src/MyComponent.tsx"
          data-component-line="6"
          data-component-file="MyComponent.tsx"
          onClick={handleClick}
        >
          Click me
        </Button>
      </MainContent>
    </div>
  )
}

With All Options Enabled

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

<Button 
  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
</Button>

Uninstalling

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

1. Remove from Vite config:

npx component-tagger-cleanup

2. Uninstall the package:

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