@autotracer/plugin-babel-react18

Babel plugin for automatic React component tracing (Next.js, CRA, Webpack).

Build-time plugin that injects useReactTracer() into eligible React components during Babel compilation so AutoTracer can attach readable component and hook labels without manual instrumentation.

Recommended Setup

Use @autotracer/plugin-babel-react18 for build-time injection only in local development or restricted internal builds, and initialize reactTracer() before your client entry renders only in those same builds.

In restricted internal browser builds, mount @autotracer/dashboard yourself when you want the standard browser control workflow. When the Dashboard is not mounted, use the lower-level runtime control surface on globalThis.autoTracer.

Theme customization stays on the runtime side through colors. File-based theme loading is available only on the Vite plugin path through ReactTracer Theme API.

Installation

# Install runtime and plugin
pnpm add @autotracer/react18
pnpm add -D @autotracer/plugin-babel-react18

# Using npm
npm install @autotracer/react18
npm install --save-dev @autotracer/plugin-babel-react18

# Using yarn
yarn add @autotracer/react18
yarn add -D @autotracer/plugin-babel-react18

If this internal browser app uses the Dashboard as its normal control surface, add it separately:

pnpm add -D @autotracer/dashboard

Usage

Add the package to your Babel config:

// babel.config.js or .babelrc
{
  "plugins": [
    [
      "@autotracer/plugin-babel-react18",
      {
        "mode": "opt-out"
      }
    ]
  ]
}

Initialize the runtime separately before your client entry renders:

async function bootstrap(): Promise<void> {
  const { reactTracer, isReactTracerInitialized } = await import(
    "@autotracer/react18"
  );

  if (!isReactTracerInitialized()) {
    reactTracer({
      enabled: false,
    });
  }
}

void bootstrap();

Use the framework guide that matches your entry path when you need full bootstrap examples:

• Installation - ReactTracer with Next.js Pages Router
• Installation - ReactTracer with Next.js App Router
• ReactTracer Installation - Create React App
• ReactTracer Configuration

Package API

This package is consumed as a Babel plugin entry in your Babel configuration. It is not a runtime initializer.

plugins: [["@autotracer/plugin-babel-react18", options]];

Supported Option Surface

• Startup and browser control: outputMode
• Eligibility and labeling: mode, pragma comments, include, exclude, labelHooks, labelHooksPattern, and prefix
• Framework and build wiring: serverComponents and importSource

What This Package Changes

• Injects useReactTracer() into eligible React function components
• Labels values returned from supported hooks so trace output keeps source-level names
• Applies mode, include, exclude, and pragma rules before instrumentation
• Restricts instrumentation to client modules with "use client" when serverComponents is enabled
• Seeds the initial runtime outputMode once per page load when outputMode is configured

Pragmas

Use line comments to control component-level injection.

• // @trace enables one eligible component.
• // @trace-disable disables one eligible component.
• include and exclude decide the eligible set before pragma signals are applied.

For exact placement rules, precedence, and examples, see the canonical Babel pragma reference.

Related Docs

• ReactTracer Babel Plugin Settings for the canonical per-setting reference
• ReactTracer Runtime Settings for reactTracer() option behavior
• @autotracer/react18 for runtime APIs and the lower-level globalThis.autoTracer control surface
• @autotracer/plugin-vite-react18 for the Vite build path
• Quick Start Guide for the recommended React entry flow