babel-plugin-transform-react-jsx-source

A Babel plugin that automatically adds source file and line number debugging information to JSX elements by injecting a __source prop containing the original source location where each JSX element is defined. This is primarily used for development debugging and React DevTools integration.

Package Information

• Package Name: babel-plugin-transform-react-jsx-source
• Package Type: npm
• Language: JavaScript
• Installation: npm install --save-dev babel-plugin-transform-react-jsx-source

Core Imports

This is a Babel plugin, so it's not imported directly in application code. Instead, it's configured in Babel configuration files.

Basic Usage

Via .babelrc (Recommended)

{
  "plugins": ["transform-react-jsx-source"]
}

Via CLI

babel --plugins transform-react-jsx-source script.js

Via Node API

require("babel-core").transform("code", {
  plugins: ["transform-react-jsx-source"]
});

Transformation Example

Input JSX:

<div>
  <span>Hello World</span>
</div>

Output after transformation:

var _jsxFileName = "/path/to/file.js";
<div __source={{ fileName: _jsxFileName, lineNumber: 1 }}>
  <span __source={{ fileName: _jsxFileName, lineNumber: 2 }}>Hello World</span>
</div>

Architecture

This plugin implements a Babel AST visitor that traverses JavaScript/JSX code and transforms JSX opening elements. It operates by:

1. Visitor Pattern: Uses Babel's visitor pattern to find JSX opening elements in the AST
2. Source Location Extraction: Reads location metadata from each JSX element
3. Variable Generation: Creates a file-scoped variable to hold the current filename
4. Attribute Injection: Adds the __source attribute with location data to JSX elements

Capabilities

Plugin Function

The main plugin export that creates a Babel AST visitor for transforming JSX elements.

/**
 * Main Babel plugin function that returns a visitor for transforming JSX elements
 * @param {Object} param - Babel plugin parameter object
 * @param {Object} param.types - Babel types (t) for AST node creation
 * @returns {Object} Babel plugin object with visitor
 */
export default function ({ types: t }) {
  // Returns { visitor: { JSXOpeningElement(path, state) { ... } } }
}

Plugin Constants

The plugin uses the following internal constants:

/** The attribute name added to JSX elements */
const TRACE_ID = "__source";

/** The variable name used for storing filename */
const FILE_NAME_VAR = "_jsxFileName";

Internal Helper Function

The plugin includes an internal helper function for creating source trace objects:

/**
 * Creates AST object expression for __source prop value
 * @param {Object} fileNameIdentifier - Reference to filename variable
 * @param {number} lineNumber - Line number where JSX element starts
 * @returns {Object} AST object with fileName and lineNumber properties
 */
function makeTrace(fileNameIdentifier, lineNumber) {
  // Returns t.objectExpression([fileNameProperty, lineNumberProperty])
}

Types

/**
 * Babel plugin structure returned by the default export
 */
interface BabelPlugin {
  /** AST visitor object containing transformation methods */
  visitor: {
    /** Visitor method for processing JSX opening elements */
    JSXOpeningElement(path, state);
  };
}

/**
 * Structure of the __source prop value added to JSX elements
 */
interface SourceInfo {
  /** The source file name where the JSX element is defined */
  fileName: string | null;
  /** The line number where the JSX element starts */
  lineNumber: number | null;
}

Plugin Behavior

Source Location Detection

• The plugin examines each JSX opening element for location information
• Elements without location data (generated elements) are skipped
• Only elements that don't already have a __source attribute are transformed

File Name Variable Generation

• A unique filename variable (e.g., _jsxFileName) is generated once per file
• The variable is declared at the file scope with the current filename as its value
• If the filename is "unknown", null is used instead

Source Prop Addition

• A __source prop is added to each qualifying JSX element
• The prop value is an object expression with fileName and lineNumber properties
• The fileName references the generated filename variable
• The lineNumber contains the line number where the JSX element starts

More Transformation Examples

Complex JSX with nested elements:

// Input
function MyComponent() {
  return (
    <div className="container">
      <h1>Title</h1>
      <button onClick={handleClick}>
        Click me
      </button>
    </div>
  );
}

// Output
var _jsxFileName = "/src/components/MyComponent.js";
function MyComponent() {
  return (
    <div className="container" __source={{ fileName: _jsxFileName, lineNumber: 3 }}>
      <h1 __source={{ fileName: _jsxFileName, lineNumber: 4 }}>Title</h1>
      <button onClick={handleClick} __source={{ fileName: _jsxFileName, lineNumber: 5 }}>
        Click me
      </button>
    </div>
  );
}

Dependencies

This plugin requires the following dependencies:

• babel-runtime: Babel runtime support
• babel-plugin-syntax-jsx: JSX syntax parsing support

Use Cases

This plugin is primarily used for:

• Development debugging: Provides source location context for React components
• Error reporting: Enables better error messages with source location information
• Developer tools: Powers React DevTools and other debugging utilities
• Source maps: Helps maintain source-to-output mapping for JSX transformations

Important: This plugin should typically be used only in development builds and excluded from production bundles for performance reasons.