Compiler Plugin

This page serves as Part.0 of configuration guide, which focuses on adding a plugin the the compiler within your development framework. The plugin will record source path information into React components during the development phase.

The <Inspector> Component of react-dev-inspector can read the source path from element's custom data attributes data-inspector- or read from React's fiber._debugSource, some compiler with plugins can provide these information.

Babel

There are some supported Babel plugins available should you need them to record source path information into React components during the development phase:

@babel/preset-react

npm i -D @babel/preset-react

@babel/preset-react (opens in a new tab) is a Babel preset that compiles JSX and other stuff to React, and most React frameworks used it as built-in preset, so maybe you don't have to install it.

If you are already using @babel/preset-react, make sure it have enabled the development option, that will provide precise code location information for debugging React apps.

{
  presets: [
    [
      '@babel/preset-react',
      {
        runtime: 'automatic', // for react >= 16.14.0
        development: process.env.NODE_ENV === 'development',
      },
    ],
  ],
}

With development and runtime: 'automatic' options enabled, it will append @babel/plugin-transform-react-jsx-development into plugins.

while set runtime: 'classic' (for react < 16.14.0), it will append legacy @babel/plugin-transform-react-jsx-source as instead.

Furthermore, you can also manually add these plugins to your Babel configuration if required.

@babel/plugin-transform-react-jsx-development

If you are already using @babel/preset-react, it will be automatically enabled by the development option so you don't have to install it.

@babel/plugin-transform-react-jsx-development (opens in a new tab) could inject the source params to _jsxDEV function, which will be transform to fiber._debugSource by React.

// Input
<div />
 
// Output
_jsxDEV("div", {}, void 0, false, {
    fileName: '/absolute/path/Component.tsx',
    lineNumber: 10,
    columnNumber: 6
  },
)

@babel/plugin-transform-react-jsx-source

The legacy plugin @babel/plugin-transform-react-jsx-source (opens in a new tab) could inject __source props to JSX Elements, which will be transform to fiber._debugSource by React.

// Input
<div />
 
// Output
<div __source={{ fileName: '/absolute/path/Component.tsx', lineNumber: 10, columnNumber: 6 }} />

@react-dev-inspector/babel-plugin

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

@react-dev-inspector/babel-plugin could inject some custom data attributes start with data-inspector-, which will eventually appear on the DOM element.

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

Setup Examples

If you wish to use a Babel plugin, please manually add it to your framework's Babel configuration, here ara some examples:

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-dev-inspector server config for vite */
    inspectorServer(),
    react({
      babel: {
        plugins: [
          '@react-dev-inspector/babel-plugin',
        ],
      },
    }),
  ],
})

SWC

No additional plugins are required when using SWC (opens in a new tab), since SWC handles this feature itself through the jsc.transform.react.development (opens in a new tab) configuration, which is usually set automatically in most frameworks.

If in your project scaffold it's not automatic set, you need to manually make sure to enable it in your swc configuration (like .swcrc):

{
  "jsc": {
    "transform": {
      "react": {
        "development": true
      }
    }
  }
}

esbuild

No additional plugins are required when using esbuild (opens in a new tab), since esbuild can indeed generate the debugSource when transforming JSX via jsx-dev option (opens in a new tab), which is usually set automatically in most frameworks.

If in your project scaffold, it's not automatic set, you need to manually make sure your esbuild has run unber jsx option with 'automatic' and jsx-dev option with true:

esbuild-loader

Example for configurate esbuild-loader (opens in a new tab) in webpack's module.rules (opens in a new tab):

{
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        loader: 'esbuild-loader',
        options: {
          loader: 'tsx',
          // https://github.com/evanw/esbuild/blob/v0.20.0/lib/shared/types.ts#L58-L67
          jsx: 'automatic',
          jsxDev: process.env.NODE_ENV === 'development',
          ...
        },
      },
    ],
  },
}