@lirankor/vite-plugin-component-tagger 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [Your Name]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @lirankor/vite-plugin-component-tagger
+
+A Vite plugin that adds data attributes to JSX elements for debugging and development purposes. This plugin helps developers identify which components and files generated specific DOM elements in the browser's developer tools.
+
+## Features
+
+- **Tags both HTML elements and React components** - Works with `<div>`, `<Button>`, `<Stack>`, etc.
+- **Precise line number tracking** - Shows exact source line where element is defined
+- **Self-closing tag support** - Handles `<Component />` syntax correctly  
+- **TypeScript-aware** - Avoids breaking TypeScript generic syntax
+- **Optimized performance** - Only runs during development when explicitly enabled
+- **Clean console output** - Minimal, informative logging
+
+## Installation
+
+```bash
+npm install @lirankor/vite-plugin-component-tagger --save-dev
+```
+
+## Usage
+
+### Basic Setup
+
+Add the plugin to your `vite.config.js` or `vite.config.ts`:
+
+```javascript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { componentTagger } from '@lirankor/vite-plugin-component-tagger'
+
+export default defineConfig({
+  plugins: [
+    componentTagger({
+      enabled: process.env.NODE_ENV === 'development'
+    }),
+    react(),
+  ],
+})
+```
+
+### Conditional Usage (Recommended)
+
+For maximum control, create a separate npm script:
+
+**package.json:**
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "dev:debug": "ENABLE_COMPONENT_TAGGER=true vite"
+  }
+}
+```
+
+**vite.config.js:**
+```javascript
+import { componentTagger } from '@lirankor/vite-plugin-component-tagger'
+
+export default defineConfig({
+  plugins: [
+    componentTagger({
+      enabled: process.env.ENABLE_COMPONENT_TAGGER === 'true'
+    }),
+    react(),
+  ],
+})
+```
+
+Then run with component tagging:
+```bash
+npm run dev:debug
+```
+
+## Generated Attributes
+
+The plugin adds three data attributes to each JSX element:
+
+- `data-dev-component`: The component file name (without extension)
+- `data-dev-file`: Full file path with line number
+- `data-dev-tag`: The HTML/React element tag name
+
+### Example Output
+
+**Source code (Button.jsx:15):**
+```jsx
+export function Button({ children }) {
+  return <button className="btn">{children}</button>
+}
+```
+
+**Generated HTML:**
+```html
+<button 
+  class="btn" 
+  data-dev-component="Button" 
+  data-dev-file="/src/components/Button.jsx:15" 
+  data-dev-tag="button"
+>
+  Click me
+</button>
+```
+
+## Configuration
+
+### Options
+
+```typescript
+interface ComponentTaggerOptions {
+  enabled?: boolean; // Default: true
+}
+```
+
+### Advanced Configuration
+
+```javascript
+componentTagger({
+  enabled: process.env.NODE_ENV === 'development' && process.env.DEBUG_COMPONENTS === 'true'
+})
+```
+
+## Use Cases
+
+### 1. Component Debugging
+Quickly identify which React component generated a specific DOM element:
+
+```javascript
+// In browser console
+const element = document.querySelector('.some-class')
+console.log(element.dataset.devComponent) // "UserProfile"
+console.log(element.dataset.devFile)      // "/src/components/UserProfile.jsx:42"
+```
+
+### 2. Visual Testing
+Perfect for visual regression testing and component identification in automated tests.
+
+### 3. Code Reviews
+Help reviewers understand the relationship between DOM structure and source code.
+
+## Important Notes
+
+- **Development only**: This plugin should only be enabled during development
+- **Build size**: Has zero impact on production builds when disabled
+- **Performance**: Minimal overhead - only processes JSX/TSX files
+- **Syntax safety**: Carefully avoids breaking TypeScript generics and complex JSX
+
+## Debugging
+
+The plugin provides helpful console output:
+
+```
+Component Tagger: Tagged 156 elements across 23 files
+```
+
+## Requirements
+
+- Vite 4.0.0 or higher
+- TypeScript/JavaScript project with JSX/TSX files
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Related
+
+- [Vite Plugin Documentation](https://vitejs.dev/guide/api-plugin.html)
+- [React Developer Tools](https://github.com/facebook/react/tree/main/packages/react-devtools)
+
+---
+
+Made for the React/Vite community

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function x(f={}){const{enabled:c=!0}=f;if(!c)return{name:"jsx-component-tagger-disabled"};let o=0,n=0;return{name:"jsx-component-tagger",enforce:"pre",buildStart(){o=0,n=0},buildEnd(){n>0&&console.log(`🏷️ Component Tagger: Tagged ${o} elements across ${n} files`)},transform(m,t){if(!c||!t.includes(".tsx")&&!t.includes(".jsx")||t.includes("node_modules"))return null;try{const a=t.split("/").pop()?.replace(/\.(tsx|jsx)$/,"")||"unknown",g=t.replace(process.cwd(),"");let r=m,i=!1,d=0;return[new RegExp("(?<![:\\w])\\s*(<(div|span|p|h[1-6]|button|form|section|main|article|header|footer|nav|aside|[A-Z][a-zA-Z0-9]*(?:[A-Z][a-zA-Z0-9]*)?)(\\s[^>]*?)?(\\/?)>)","g")].forEach(p=>{r=r.replace(p,(s,e,b,A,C,h)=>{const v=(r.substring(0,h).match(/\n/g)||[]).length+1;if(e.includes("data-dev-component")||e.includes("=>")||e.includes("() =>")||e.includes(`
+`))return s;const u=` data-dev-component="${a}" data-dev-file="${g}:${v}" data-dev-tag="${b}"`;let l;e.endsWith("/>")?l=e.slice(0,-2)+u+" />":l=e.slice(0,-1)+u+">";const $=s.replace(e,l);return i=!0,d++,$})}),i?(o+=d,n++,{code:r,map:null}):null}catch(a){return console.warn(`JSX tagger failed for ${t}:`,a),null}}}}exports.componentTagger=x;

package/dist/index.js

@@ -0,0 +1,48 @@
+function w(f = {}) {
+  const { enabled: c = !0 } = f;
+  if (!c)
+    return {
+      name: "jsx-component-tagger-disabled"
+    };
+  let o = 0, n = 0;
+  return {
+    name: "jsx-component-tagger",
+    enforce: "pre",
+    // Run before esbuild and other core plugins
+    buildStart() {
+      o = 0, n = 0;
+    },
+    buildEnd() {
+      n > 0 && console.log(`🏷️ Component Tagger: Tagged ${o} elements across ${n} files`);
+    },
+    transform(m, t) {
+      if (!c || !t.includes(".tsx") && !t.includes(".jsx") || t.includes("node_modules"))
+        return null;
+      try {
+        const a = t.split("/").pop()?.replace(/\.(tsx|jsx)$/, "") || "unknown", p = t.replace(process.cwd(), "");
+        let r = m, i = !1, d = 0;
+        return [new RegExp("(?<![:\\w])\\s*(<(div|span|p|h[1-6]|button|form|section|main|article|header|footer|nav|aside|[A-Z][a-zA-Z0-9]*(?:[A-Z][a-zA-Z0-9]*)?)(\\s[^>]*?)?(\\/?)>)", "g")].forEach((g) => {
+          r = r.replace(g, (s, e, b, A, C, h) => {
+            const $ = (r.substring(0, h).match(/\n/g) || []).length + 1;
+            if (e.includes("data-dev-component") || e.includes("=>") || e.includes("() =>") || e.includes(`
+`))
+              return s;
+            const u = ` data-dev-component="${a}" data-dev-file="${p}:${$}" data-dev-tag="${b}"`;
+            let l;
+            e.endsWith("/>") ? l = e.slice(0, -2) + u + " />" : l = e.slice(0, -1) + u + ">";
+            const v = s.replace(e, l);
+            return i = !0, d++, v;
+          });
+        }), i ? (o += d, n++, {
+          code: r,
+          map: null
+        }) : null;
+      } catch (a) {
+        return console.warn(`JSX tagger failed for ${t}:`, a), null;
+      }
+    }
+  };
+}
+export {
+  w as componentTagger
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@lirankor/vite-plugin-component-tagger",
+  "version": "1.0.3",
+  "description": "A Vite plugin that adds data attributes to JSX elements for debugging and development purposes",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && vite build",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "vite",
+    "plugin",
+    "vite-plugin",
+    "react",
+    "jsx",
+    "tsx",
+    "debugging",
+    "development", 
+    "devtools",
+    "component",
+    "tagging",
+    "data-attributes",
+    "inspector",
+    "dom-debugging"
+  ],
+  "author": "Liran Koren",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lirankor/vite-plugin-component-tagger.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lirankor/vite-plugin-component-tagger/issues"
+  },
+  "homepage": "https://github.com/lirankor/vite-plugin-component-tagger#readme",
+  "peerDependencies": {
+    "vite": "^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.1",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.2"
+  }
+}