react-simple-inspector

Dev-only "click to source" inspector for Vite + React.

Press Cmd+X (Ctrl+X on Windows/Linux) to toggle inspect mode. Hover any element to outline it and see its owning component, tag, and file:line. Click to open that exact line in your editor. Esc exits. Never ships in a production build (apply: 'serve').

How it works

• A pre Vite transform stamps every host (lowercase) JSX element with data-inspect="file:line:col" and data-inspect-name="Owner › tag" by splicing text (no reprint, source maps preserved). Works with both @vitejs/plugin-react (Babel) and plugin-react-swc — it does not depend on the React plugin.
• A shadow-DOM overlay (injected only by the dev server) reads those attributes.
• A dev-server endpoint GET /__inspector/open?loc=file:line:col opens the file via <editor> --goto, root-guarded against path traversal.

Install

pnpm add -D react-simple-inspector

Usage

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { inspectorPlugin } from "react-simple-inspector";

export default defineConfig(({ command }) => ({
  plugins: [
    react(),
    // dev only
    ...(command === "serve" ? [inspectorPlugin()] : [])
  ]
}));

Options

inspectorPlugin({
  editor: "code", // command or absolute path to launch; default "cursor"
  root: process.cwd(), // stamped paths are relative to this; default process.cwd()
  hotkey: "mod+x" // toggle combo; default "mod+x"
});

editor

The editor to open the clicked file in, launched as <editor> --goto <file>:<line>:<col>.

You usually don't need to touch this. If the command (cursor, code, …) isn't on your PATH — common, since the "Install '' command in PATH" palette step is easy to miss, and GUI-launched dev servers often have a stripped PATH — the plugin automatically falls back to the editor's known install location for your platform (Cursor, VS Code / Insiders, VSCodium, Windsurf). So a plain install just works without any PATH setup.

Resolution order: the value as given (via PATH) → known install locations → a one-time warning telling you how to fix it. Pass an absolute path to force a specific binary:

inspectorPlugin({ editor: "/Applications/Cursor.app/Contents/Resources/app/bin/cursor" });

hotkey

Any key combination — "+"-joined modifiers plus an optional final key. Case-insensitive. Examples:

| Value | Triggers on | | ----------------- | ------------------------------- | | "mod+x" | ⌘X on Mac, Ctrl+X elsewhere | | "ctrl+shift+i" | Ctrl+Shift+I everywhere | | "alt+\" | Alt+backtick | |"F2"` | just F2, no modifiers |

Modifier aliases: mod (⌘ on Mac / Ctrl elsewhere), cmd/command/meta/win, ctrl/control, shift, alt/option. Unspecified modifiers must be released for the combo to match. The hotkey is ignored while focus is in an input, textarea, or contenteditable. Esc always exits inspect mode.