superdev-tagger/README.md

Vite plugin for component tagging

# SuperDev Tagger

A lightweight utility for tagging React components in Vite-based applications with custom data attributes.

## Installation

```bash
npm install superdev-tagger
# or
yarn add superdev-tagger
```

## Features

This package provides two main features:

1. **Component Tagging HOC** - A higher-order component that wraps your React components with custom data attributes
2. **Vite Plugin** - A plugin that automatically tags JSX/TSX components in your Vite application

## Usage - Component Tagging HOC

### Basic Usage

```tsx
import { tagComponent } from 'superdev-tagger';
import MyComponent from './MyComponent';

// Tag a component with default options
const TaggedComponent = tagComponent(MyComponent);

// Usage
function App() {
  return <TaggedComponent />;
  // Renders as: <div data-component="MyComponent">...</div>
}
```

### With Custom Options

```tsx
import { tagComponent } from 'superdev-tagger';
import MyComponent from './MyComponent';

// Tag with custom options
const TaggedComponent = tagComponent(MyComponent, {
  id: 'unique-id',
  attributes: {
    'feature': 'search',
    'version': '1.2.0'
  }
});

// Usage
function App() {
  return <TaggedComponent />;
  // Renders as: <div data-component="MyComponent" data-component-id="unique-id" data-feature="search" data-version="1.2.0">...</div>
}
```

### Override Options at Runtime

```tsx
function App() {
  return (
    <TaggedComponent 
      tagOptions={{
        id: 'runtime-id',
        attributes: {
          'feature': 'dynamic-search'
        }
      }}
    />
  );
}
```

## Usage - Vite Plugin

Add the plugin to your Vite configuration:

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

export default defineConfig({
  plugins: [
    react(),
    componentTagger()
  ],
});
```

This will automatically add data attributes to your JSX/TSX components:

```tsx
// Your component
function Button() {
  return <button>Click me</button>;
}

// After processing by the plugin, it becomes:
// <button data-lov-id="Button.tsx:2:10" data-lov-name="button" data-component-path="Button.tsx" data-component-line="2" data-component-file="Button.tsx" data-component-name="button" data-component-content="{\"text\":\"Click me\"}">Click me</button>
```

## API

### tagComponent(Component, options?)

Creates a higher-order component that wraps the provided component with additional data attributes.

#### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `id` | `string` | `undefined` | A unique identifier for the component |
| `attributes` | `Record<string, string>` | `{}` | Custom data attributes to add |
| `includeComponentName` | `boolean` | `true` | Whether to include component name |

### componentTagger()

Creates a Vite plugin that automatically tags JSX/TSX components with data attributes.

## License

MIT # superdev-tagger