component-tagger/README.md

A Vite plugin that automatically adds comprehensive component tagging attributes to JSX/TSX elements for debugging and testing

# 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

### Basic Setup

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

### Custom Configuration

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

### Before Transformation

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

### After Transformation (Default Settings)

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

```tsx
// 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:**
```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