@vibetorch/inspector

A powerful DOM inspector for React applications that enables visual element selection with component information extraction.

Features

• 🎯 Visual Element Selection - Click to select any element on the page
• 🧩 React Component Detection - Automatically extracts React component names and props
• 📍 Source Location - Shows file location and line numbers (development mode)
• 📨 PostMessage Communication - Built-in iframe ↔ parent window communication
• ⌨️ Keyboard Shortcuts - Cmd+Shift+C (Mac) or Ctrl+Shift+C to activate
• 🎨 Customizable - Configurable colors, shortcuts, and behavior
• 📦 Zero Config - Works out of the box with auto-initialization

Installation

npm install @vibetorch/inspector --save-dev
# or
yarn add @vibetorch/inspector -D
# or
pnpm add @vibetorch/inspector -D

Quick Start

Option 1: Auto-initialization (Recommended)

The inspector automatically initializes in development mode. Just install and it works!

// The inspector is automatically available in development
// Press Cmd+Shift+C (Mac) or Ctrl+Shift+C to activate

Option 2: Manual Initialization

import { VibetorchInspector } from '@vibetorch/inspector'

// Initialize manually
const inspector = new VibetorchInspector({
  enabled: process.env.NODE_ENV === 'development',
  onElementSelected: (info) => {
    console.log('Selected element:', info)
  }
})

// Start inspection
inspector.start()

Option 3: With Vite Plugin

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { vibetorchInspectorPlugin } from '@vibetorch/inspector/vite'

export default defineConfig({
  plugins: [
    react(),
    vibetorchInspectorPlugin({
      enabled: process.env.NODE_ENV === 'development',
      includeSource: true  // Add source location to elements
    })
  ]
})

Usage

Basic Usage

1. Activate Inspector: Press Cmd+Shift+C (Mac) or Ctrl+Shift+C (Windows/Linux)
2. Select Element: Move your mouse over elements to highlight them
3. Click to Select: Click on any element to select it
4. ESC to Cancel: Press ESC to exit inspection mode

Programmatic Control

// Get the global instance
const inspector = window.__vibetorchInspector

// Start inspection
inspector.start()

// Stop inspection
inspector.stop()

// Toggle inspection
inspector.toggle()

// Check if inspecting
const isActive = inspector.isInspecting()

// Manually analyze an element
const info = inspector.analyzeElement(document.querySelector('#my-element'))

API

VibetorchInspector

class VibetorchInspector {
  constructor(config?: InspectorConfig)
  start(): void
  stop(): void
  toggle(): void
  isInspecting(): boolean
  analyzeElement(element: Element): ElementInfo
}

Configuration Options

interface InspectorConfig {
  enabled?: boolean              // Enable/disable inspector
  onElementSelected?: (info: ElementInfo) => void
  onElementHovered?: (info: ElementInfo) => void
  enableShortcuts?: boolean       // Enable keyboard shortcuts
  shortcutKey?: string           // Custom shortcut (e.g., 'cmd+shift+i')
  theme?: 'light' | 'dark'       // UI theme
  targetOrigin?: string          // PostMessage target origin
  highlightColor?: string        // Element highlight color
}

Element Information

interface ElementInfo {
  tagName: string
  xpath: string
  selector: string
  text: string
  className: string
  id: string
  react?: {
    componentName: string
    props?: Record<string, any>
    source?: {
      fileName: string
      lineNumber: number
    }
  }
  semantic?: {
    label?: string
    role?: string
    actionText?: string
  }
}

iframe Communication

The inspector includes built-in PostMessage communication for iframe scenarios:

In the iframe (child window)

import { VibetorchInspector } from '@vibetorch/inspector'

new VibetorchInspector({
  onElementSelected: (info) => {
    // Automatically sends to parent window
    // Message type: 'vibetorch:element-selected'
  }
})

In the parent window

window.addEventListener('message', (event) => {
  if (event.data.type === 'vibetorch:element-selected') {
    console.log('Element selected in iframe:', event.data.data)
  }
})

// Control inspector in iframe
iframe.contentWindow.postMessage({
  type: 'vibetorch:start-inspector'
}, '*')

Advanced Usage

Custom Message Bridge

import { MessageBridge } from '@vibetorch/inspector'

const bridge = new MessageBridge()

// Send to parent
bridge.sendToParent('custom-event', { data: 'value' })

// Listen for messages
bridge.on('custom-event', (data) => {
  console.log('Received:', data)
})

React Bridge Direct Access

import { ReactBridge } from '@vibetorch/inspector'

const reactBridge = new ReactBridge()
const componentInfo = reactBridge.getComponentInfo(element)

Examples

With Next.js

// pages/_app.tsx or app/layout.tsx
import { useEffect } from 'react'
import { VibetorchInspector } from '@vibetorch/inspector'

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    if (process.env.NODE_ENV === 'development') {
      new VibetorchInspector()
    }
  }, [])
  
  return <Component {...pageProps} />
}

With Create React App

// src/index.js
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'

if (process.env.NODE_ENV === 'development') {
  import('@vibetorch/inspector').then(({ VibetorchInspector }) => {
    new VibetorchInspector()
  })
}

const root = ReactDOM.createRoot(document.getElementById('root'))
root.render(<App />)

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Inspired by React DevTools and various DOM inspection tools.