vite-plugin-component-debugger

A Vite plugin that automatically adds data attributes to JSX/TSX elements during development, making it easier to track, debug, and understand component rendering in your React applications.

Features

• 🏷️ Automatic Tagging: Adds data attributes to JSX/TSX elements with component information
• 📍 Location Tracking: Includes file path, line number, and column for each component
• 📦 Props Collection: Optionally captures component props in the metadata
• 📝 Content Extraction: Can include text content from components
• 🎯 Selective Tagging: Configurable exclusion rules for specific elements
• ⚡ Performance Focused: Minimal impact on build times
• 🔧 Fully Configurable: Extensive options for customization

Installation

npm install --save-dev vite-plugin-component-debugger

or

yarn add -D vite-plugin-component-debugger

or

pnpm add -D vite-plugin-component-debugger

Usage

Basic Setup

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import componentTagger from 'vite-plugin-component-debugger';

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

With Configuration

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import componentTagger from 'vite-plugin-component-debugger';

export default defineConfig({
  plugins: [
    react(),
    componentTagger({
      // Custom prefix for data attributes
      attributePrefix: 'data-dev',
      
      // File extensions to process
      extensions: ['.jsx', '.tsx'],
      
      // Elements to exclude from tagging
      excludeElements: ['Fragment', 'React.Fragment'],
      
      // Include component props in metadata
      includeProps: true,
      
      // Include text content
      includeContent: true,
      
      // Custom elements to exclude (e.g., Three.js elements)
      customExcludes: new Set(['mesh', 'group', 'camera']),
      
      // Enable/disable the plugin
      enabled: process.env.NODE_ENV === 'development'
    })
  ]
});

Output Example

Given this React component:

// src/components/Button.tsx (line 10)
<button className="btn-primary" onClick={handleClick}>
  Click me
</button>

The plugin will transform it to:

<button 
  data-dev-id="src/components/Button.tsx:10:2"
  data-dev-name="button"
  data-dev-path="src/components/Button.tsx"
  data-dev-line="10"
  data-dev-file="Button.tsx"
  data-dev-component="button"
  data-dev-metadata="%7B%22className%22%3A%22btn-primary%22%2C%22text%22%3A%22Click%20me%22%7D"
  className="btn-primary" 
  onClick={handleClick}
>
  Click me
</button>

Configuration Options

Use Cases

1. Development Debugging

Quickly identify which component rendered which element in the DOM:

// In browser console
document.querySelectorAll('[data-dev-component="Button"]')
  .forEach(el => {
    console.log(`Button at ${el.dataset.devPath}:${el.dataset.devLine}`);
  });

2. Automated Testing

Use the data attributes in your E2E tests:

// Cypress example
cy.get('[data-dev-component="SubmitButton"]').click();
cy.get('[data-dev-path*="LoginForm"]').should('be.visible');

3. Performance Monitoring

Track component render locations:

const observer = new MutationObserver((mutations) => {
  mutations.forEach((mutation) => {
    if (mutation.type === 'childList') {
      mutation.addedNodes.forEach((node) => {
        if (node.dataset?.devId) {
          console.log(`Component added: ${node.dataset.devId}`);
        }
      });
    }
  });
});

4. Visual Debugging Tools

Build custom debugging overlays:

// Show component boundaries on hover
document.addEventListener('mouseover', (e) => {
  const target = e.target;
  if (target.dataset?.devComponent) {
    target.style.outline = '2px solid red';
    console.log(`Component: ${target.dataset.devComponent}`);
    console.log(`Location: ${target.dataset.devPath}:${target.dataset.devLine}`);
  }
});

Environment-based Configuration

Only enable in development:

export default defineConfig({
  plugins: [
    react(),
    componentTagger({
      enabled: process.env.NODE_ENV === 'development'
    })
  ]
});

Or with different configs per environment:

const isDev = process.env.NODE_ENV === 'development';
const isStaging = process.env.NODE_ENV === 'staging';

export default defineConfig({
  plugins: [
    react(),
    componentTagger({
      enabled: isDev || isStaging,
      attributePrefix: isStaging ? 'data-staging' : 'data-dev',
      includeProps: isDev, // Only include props in development
    })
  ]
});

Working with React Three Fiber

The plugin automatically excludes Three.js/React Three Fiber elements by default:

componentTagger({
  // These are excluded by default:
  customExcludes: new Set([
    'mesh', 'group', 'scene', 'camera',
    'ambientLight', 'directionalLight', 'pointLight',
    'boxGeometry', 'sphereGeometry', 'planeGeometry',
    'meshBasicMaterial', 'meshStandardMaterial',
    // ... and many more
  ])
});

To include them:

componentTagger({
  customExcludes: new Set() // Empty set to tag everything
});

Build Statistics

The plugin provides build statistics in the console:

📊 Component Debugger Statistics:
   Total files scanned: 45
   Files processed: 32
   Elements tagged: 287

Performance Considerations

• The plugin runs only during build/development
• Uses efficient AST traversal with caching
• Minimal impact on HMR (Hot Module Replacement)
• Automatically skips node_modules

TypeScript Support

The plugin is written in TypeScript and provides full type definitions:

import componentTagger, { type TagOptions } from 'vite-plugin-component-debugger';

const config: TagOptions = {
  enabled: true,
  attributePrefix: 'data-track'
};

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

Troubleshooting

Elements not being tagged

1. Check that the file extension is included in extensions
2. Verify the element isn't in excludeElements or customExcludes
3. Ensure the plugin is enabled

Build performance issues

1. Reduce the scope by limiting extensions
2. Add more elements to excludeElements
3. Disable includeProps and includeContent if not needed

Attributes not showing in production

Make sure to disable the plugin in production:

componentTagger({
  enabled: process.env.NODE_ENV !== 'production'
})

Inspiration

This plugin was inspired by lovable-tagger, bringing similar functionality to the Vite ecosystem with enhanced features for React development.

Contributing

We welcome contributions! Here's how you can help:

🐛 Bug Reports

• Use the issue tracker to report bugs
• Include a minimal reproduction case
• Specify your Vite, React, and plugin versions

💡 Feature Requests

• Open an issue describing the feature
• Explain the use case and expected behavior
• Consider implementing it yourself via PR!

🤝 Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b my-feature
3. Make your changes and add tests
4. Run the full test suite: pnpm run check
5. Commit with a clear message
6. Push and open a pull request

🔧 Development Setup

# Clone and install
git clone https://github.com/yourusername/vite-plugin-component-debugger.git
cd vite-plugin-component-debugger
pnpm install

# Run tests
pnpm run test

# Build and test
pnpm run build
pnpm run check

📝 Code Guidelines

• Follow existing code style
• Add tests for new features
• Update documentation as needed
• Ensure TypeScript types are correct

Author

Tonye Brown is a seasoned front-end developer and designer, crafting immersive web experiences of various scales and complexities. Guided by 5 principles for excellence and a deep-rooted passion for creativity and innovation, he blends coding expertise with an unerring eye for design.

His mission is to help brands forge meaningful & memorable connections with their customers through highly performant and beautifully designed web & digital experiences. Beyond code, he's also a Music Producer and Artist.

Connect with Tonye:

• 🌐 Website: www.tonyebrown.com
• 📖 Plugin Documentation: www.tonyebrown.com/apps/vite-plugin-component-debugger
• 🐦 Twitter: @truevined
• 💼 LinkedIn: /in/tonyeb

Support This Project: If this plugin helps improve your development workflow, consider supporting its development:

• ⭐ Star this repository
• ☕ Buy me a coffee
• 💝 Sponsor on GitHub

Your support helps maintain and improve this plugin! 🙏

License

MIT License - see LICENSE file for details

Support

If you find this plugin helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting issues on GitHub
• 💡 Suggesting new features
• 🤝 Contributing code via pull requests
• 📢 Sharing with other developers