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