React Dev Inspector

React Dev Inspector is a tool designed for seamless code navigation from the browser to your local IDE. It allows you to click on a React component in the browser and instantly jump to its source code in your editor.

Key features include:

• No browser restrictions or framework limitations.
• Works with local, remote, or containerized environments.
• Supports both development and production build modes.
• Designed to be integrated into custom tools like browser extensions or developer toolkits.

The @react-dev-inspector/web-components package provides the Web UI components used by react-dev-inspector. These components are built using solid-js and are exported as standard Web Components.

Key components include:

• Overlay: The main inspector UI. It supports custom boxSizing and bounding configurations.
• InspectContextPanel: A floating, draggable, and resizable context menu used to display the element hierarchy.

The Compiler Plugin is an optional part of the react-dev-inspector configuration. Its purpose is to record source path information (file name, line number, and column) into React components during development. This information allows the <Inspector> component to map DOM elements back to their original source code.

Most modern React frameworks provide this information out-of-the-box, so manual configuration is often unnecessary. The <Inspector> component can retrieve this data from either:

1. Custom data attributes starting with data-inspector-.
2. React's internal fiber._debugSource property.

If your framework does not automatically provide this, you must configure a compiler plugin (Babel, SWC, or esbuild) as described in the following sections.

The Umi4 plugin includes @react-dev-inspector/babel-plugin. This Babel plugin is automatically disabled under the following conditions:

1. When your Umi4 configuration uses srcTranspiler: 'swc'.
2. When you are running a production build.

The tool operates through a three-part pipeline:

1. Inject JSX Source (Optional): A compiler plugin records source path information into React components during the development stage. Most frameworks support this out-of-the-box.
2. Inspector Component: The <Inspector/> component reads the injected source info and sends it to the dev-server when you inspect elements in the browser.
3. Dev Server Middleware: Middleware integrated into your dev-server receives the source path info via an API and calls your local IDE/Editor to open the specific source file.

The @react-dev-inspector/babel-plugin injects custom data attributes into your JSX elements during the compilation process. These attributes allow the inspector to map DOM elements back to their original source code location.

Note: This step is generally OPTIONAL. Most modern React frameworks provide this functionality out-of-the-box. You typically only need to configure this manually if your build pipeline does not already support these features or if you are using a custom Babel setup.

// Input
<div />

// Output
<div data-inspector-relative-path="src/path/Component.tsx" data-inspector-line="10" data-inspector-column="6" />

As of v2.1.0-beta.10, the Inspector implementation has been refactored into DOMInspectAgent. This allows you to set custom InspectAgent implementations to work alongside the default DOMInspectAgent.

To build custom agents, you can use the following exported utilities:

• fiberUtils: For accessing React Fiber nodes.
• inspectUtils: General utilities to assist with the inspection process.

Additionally, the @react-dev-inspector/web-components package provides:

• Overlay: The UI indicating the inspected element. It supports custom logic for boxSizing and bounding.
• InspectContextPanel: A draggable and resizable floating context-menu panel triggered by right-click inspection.

To use react-dev-inspector in a Vite project, you need to install the @react-dev-inspector/vite-plugin package and add the inspectorServer plugin to your vite.config.ts. This plugin registers a middleware that enables the local editor launch functionality. It is compatible with Vite versions 2, 3, 4, and 5.

npm i -D @react-dev-inspector/vite-plugin

Add inspectorServer() to the plugins array in your vite.config.ts file. This plugin registers an inspectorServer middleware that allows the local editor to launch via an endpoint. It is compatible with vite@5, vite@4, vite@3, and vite@2.

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { inspectorServer } from '@react-dev-inspector/vite-plugin'

// https://vitejs.dev/config/
export default defineConfig({
  ...

  plugins: [
    react(),

    /**
     * react-dev-inspector server config for vite
     */
    inspectorServer(),
  ],
})

To enable the ability to open source files directly in your local IDE/Editor from the React Dev Inspector, you must implement a Dev Server Middleware. This middleware acts as a bridge that receives API requests from the Inspector Component and triggers the local editor on the server side.

Prerequisites: Before setting up the middleware, you must have already completed Part 1: adding the Inspector Component to your project.

To use Neovim or Vim, set the REACT_EDITOR environment variable to nvim or vim in your shell configuration file.

export REACT_EDITOR=nvim
# or
export REACT_EDITOR=vim