vite-plugin-component-registry

A Vite plugin that injects component metadata into your React application for enhanced dev tools support.

⚠️ DEVELOPMENT ONLY: This plugin is designed for development mode only. While it's safe by default (devOnly: true), never set devOnly: false in production as it will expose file paths in your HTML.

Features

• 🎯 Inject component metadata (file, line, column) into DOM elements
• 🔄 Two strategies: Babel AST transformation (build-time) or React Fiber (runtime)
• 🛠️ Runtime API for extracting component information
• 📦 Optional static component registry generation
• ⚡ Zero runtime overhead in production (dev-only by default)

Installation

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

Usage

Basic Setup

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import componentRegistry from 'vite-plugin-component-registry';

export default defineConfig({
  plugins: [
    react(),
    componentRegistry({
      // Options (all optional)
      include: ['src/**/*.{tsx,jsx}'],
      exclude: ['node_modules/**'],
      injectTags: ['div', 'button', 'input', 'section'],
      strategy: 'babel', // or 'runtime'
    }),
  ],
});

Using the Runtime API

The registry is automatically initialized by the plugin. You can access it directly:

// In your dev tools or debugging code
import { initComponentRegistry } from 'vite-plugin-component-registry/client';

// Optional: Get the registry instance (it's already initialized)
const registry = initComponentRegistry();

  // Get metadata for an element
  const element = document.querySelector('.my-component');
  const metadata = registry.getMetadata(element);
  console.log(metadata);
  // {
  //   id: "Button_15_2",
  //   file: "src/components/Button.tsx",
  //   line: 15,
  //   column: 2,
  //   componentName: "Button",
  //   parentComponent: "Hero",      // NEW: Parent component name
  //   parentFile: "src/sections/Hero.tsx"  // NEW: Parent component file
  // }

  // Listen for component clicks (optional)
  const cleanup = registry.onComponentClick((metadata) => {
    console.log('Clicked component:', metadata);
    console.log(`Rendered by: ${metadata.parentComponent} in ${metadata.parentFile}`);
  });
}

// Or use the global API directly in browser console:
// window.__COMPONENT_REGISTRY__.getMetadata(element)

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | include | string[] | ['**/*.{tsx,jsx}'] | Files to include (glob patterns) | | exclude | string[] | ['node_modules/**', 'dist/**'] | Files to exclude (glob patterns) | | injectTags | string[] | ['div', 'button', 'input', 'section', 'main', 'header', 'footer'] | HTML tags to inject metadata into | | devOnly | boolean | true | Enable only in development | | strategy | 'babel' \| 'runtime' | 'babel' | Transformation strategy | | generateRegistry | boolean | false | Generate static component registry JSON | | registryOutput | string | 'public/component-registry.json' | Output path for registry JSON |

Strategies

Babel Strategy (Recommended)

Uses AST transformation to inject metadata at build time. More reliable and works with all React components.

componentRegistry({ strategy: 'babel' })

Runtime Strategy

Uses React Fiber to extract metadata at runtime. Lighter build-time overhead but requires React DevTools mode.

componentRegistry({ strategy: 'runtime' })

License

MIT