React XRay 🩻

Surgically edit your React apps in the browser.

Quickstart

npm i @p0u4a/react-xray

Add the plugin to your Vite config:

import { xray } from "@p0u4a/react-xray";

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

Now when you start your dev server, you'll see the XRay widget. Activate XRay mode by pressing option+X (Mac) or alt+X (Windows).

Select any element on the page, and you'll see a popover with the code for that component open. Edit the code and see the component update in real time via HMR.

Plugin Options

editorTheme

Accepts any bundled Shiki theme name. Defaults to tokyo-night.

endpoint

The base URL for the local X-Ray dev server endpoints. Defaults to /__xray.

shortcut

The keyboard shortcut used to toggle inspection mode. Defaults to option+X on macOS and alt+X on other platforms.

include

An allowlist for instrumentation. Accepts either:

• A RegExp
• A function (filePath: string) => boolean

The matcher runs against the full file path after Vite query params are stripped. Only .jsx and .tsx files outside node_modules are considered.

exclude

A denylist for instrumentation. Accepts the same filter types as include and is evaluated after include.

Example:

xray({
  include: /\/src\/components\//,
  exclude: (filePath) => filePath.endsWith(".stories.tsx"),
});

How it works

During development, the plugin transforms your JSX source files and injects a data-xray attribute onto every native HTML element. The value is a hash that encode's the element's file path, line number, and column number.

When you select an element with XRay, the runtime reads the hash from the DOM and sends it to the dev server at /__xray/resolve, where a registry maps it back to the exact file path, line, column, and enclosing React component name. The runtime then fetches the file contents from /__xray/file and displays them in the popover.

When you save an edit, the runtime POSTs the updated contents to /__xray/save, which writes the file to disk. The registry tracks file versions using filesystem fingerprints, so if the file was modified externally between your load and save, it rejects with a conflict. After a write Vite detects the change and triggers HMR as normal.