React

The @domscribe/react package provides React fiber walking, props/state extraction, and bundler plugins for Vite and Webpack.

Install

npm install -D @domscribe/react

Vite Setup

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { domscribe } from '@domscribe/react/vite';

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

Webpack Setup

Webpack requires both a loader (for AST transformation) and a plugin (for relay and overlay coordination):

// webpack.config.js
const { DomscribeWebpackPlugin } = require('@domscribe/react/webpack');

const isDevelopment = process.env.NODE_ENV !== 'production';

module.exports = {
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,
        enforce: 'pre',
        use: [
          {
            loader: '@domscribe/transform/webpack-loader',
            options: { enabled: isDevelopment },
          },
        ],
      },
    ],
  },
  plugins: [
    new DomscribeWebpackPlugin({
      enabled: isDevelopment,
      overlay: true,
    }),
  ],
};

Supported Versions

React 18 and React 19
Vite 5 - 7
Webpack 5

Plugin Options

The React plugin extends the base transform options with runtime and capture namespaces:

domscribe({
  // Base transform options
  include: /\.(jsx|tsx)$/,
  exclude: /node_modules/,
  debug: false,
  relay: { autoStart: true, port: 0, host: '127.0.0.1' },
  overlay: true,

  // React-specific
  runtime: { /* ... */ },
  capture: { /* ... */ },
})

Runtime Options

Option	Type	Default	Description
`phase`	`1 \| 2`	`1`	Feature phase gate. Phase 1: props/state. Phase 2: events/perf.
`redactPII`	`boolean`	`true`	Redact sensitive values in captured data.
`blockSelectors`	`string[]`	`[]`	CSS selectors to exclude from capture.

Capture Options

Option	Type	Default	Description
`strategy`	`'devtools' \| 'fiber' \| 'best-effort'`	`'best-effort'`	Capture strategy (see below).
`maxTreeDepth`	`number`	`50`	Maximum component tree depth to traverse.
`includeWrappers`	`boolean`	`true`	Include HOC/memo/forwardRef wrapper components.
`hookNameResolvers`	`Record<string, Record<number, string>>`	`undefined`	Map component names to hook index to semantic name mappings.

Capture Strategies

The React adapter supports three strategies for accessing component data:

devtools -- uses the React DevTools global hook (window.__REACT_DEVTOOLS_GLOBAL_HOOK__). Most reliable, but requires React DevTools to be installed.
fiber -- accesses the React Fiber tree directly via internal __reactFiber$ properties on DOM elements. Fast, but relies on React internal APIs.
best-effort (default) -- tries multiple strategies in order of reliability and uses whichever succeeds.

Hook Name Resolvers

By default, React hook state appears as indexed values (hook 0, hook 1, etc.). You can provide semantic names for better readability:

domscribe({
  capture: {
    hookNameResolvers: {
      Counter: { 0: 'count', 1: 'setCount' },
      TodoList: { 0: 'items', 1: 'filter' },
    },
  },
})

Subpath Exports

@domscribe/react/vite -- Vite plugin with React adapter
@domscribe/react/webpack -- Webpack plugin with React adapter
@domscribe/react/auto-init -- Auto-initialization module