or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-babel--plugin-transform-react-jsx-development

Babel plugin that transforms JSX into React function calls with development-specific debugging features

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@babel/plugin-transform-react-jsx-development@7.27.x

To install, run

npx @tessl/cli install tessl/npm-babel--plugin-transform-react-jsx-development@7.27.0

index.mddocs/

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

Babel plugin that transforms JSX syntax into React function calls with development-specific debugging features. This plugin extends the core @babel/plugin-transform-react-jsx functionality to include enhanced debugging information, source location tracking, and runtime warnings that help developers identify issues during development.

Package Information

  • Package Name: @babel/plugin-transform-react-jsx-development
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev @babel/plugin-transform-react-jsx-development

Core Imports

Since this is a Babel plugin, it's typically configured in Babel configuration files rather than imported directly:

{
  "plugins": ["@babel/plugin-transform-react-jsx-development"]
}

For programmatic usage with Babel API:

const babel = require("@babel/core");
const plugin = require("@babel/plugin-transform-react-jsx-development");

const result = babel.transform(code, {
  plugins: [plugin]
});

ES modules:

import * as babel from "@babel/core";
import plugin from "@babel/plugin-transform-react-jsx-development";

Basic Usage

Babel Configuration

Add the plugin to your .babelrc or babel.config.js:

{
  "plugins": ["@babel/plugin-transform-react-jsx-development"]
}

With Options

{
  "plugins": [
    ["@babel/plugin-transform-react-jsx-development", {
      "runtime": "automatic",
      "importSource": "react"
    }]
  ]
}

Transformation Example

Input JSX:

function App() {
  return (
    <div>
      <h1>Hello World</h1>
      <p>React with debugging info</p>
    </div>
  );
}

Output (Classic Runtime):

var _jsxFileName = "/path/to/file.js";
function App() {
  return /*#__PURE__*/React.createElement("div", {
    __self: this,
    __source: {
      fileName: _jsxFileName,
      lineNumber: 3,
      columnNumber: 5
    }
  }, /*#__PURE__*/React.createElement("h1", {
    __self: this,
    __source: {
      fileName: _jsxFileName,
      lineNumber: 4,
      columnNumber: 7
    }
  }, "Hello World"), /*#__PURE__*/React.createElement("p", {
    __self: this,
    __source: {
      fileName: _jsxFileName,
      lineNumber: 5,
      columnNumber: 7
    }
  }, "React with debugging info"));
}

Capabilities

Plugin Function

The main Babel plugin function that processes JSX syntax and adds development debugging features.

import type { PluginObj, PluginPass } from "@babel/core";
import type { JSXElement, JSXFragment, Node } from "@babel/types";

declare const plugin: () => PluginObj<PluginPass>;
export default plugin;

Plugin Options

Configuration options for customizing the JSX transformation behavior.

import type { Node } from "@babel/types";
import type { PluginPass } from "@babel/core";

interface Options {
  /** Optional filter function to control which nodes are processed (classic runtime only) */
  filter?: (node: Node, pass: PluginPass) => boolean;
  
  /** The module to import JSX functions from (default: "react") */
  importSource?: string;
  
  /** The function to use for JSX elements in classic runtime (default: "React.createElement") */
  pragma?: string;
  
  /** The function to use for JSX fragments in classic runtime (default: "React.Fragment") */
  pragmaFrag?: string;
  
  /** Mark the output as pure for tree-shaking optimization */
  pure?: string;
  
  /** JSX runtime mode - "automatic" uses new JSX transform, "classic" uses createElement */
  runtime?: "automatic" | "classic";
  
  /** Whether to throw an error when JSX namespace is used (default: true) */
  throwIfNamespace?: boolean;
  
  /** Whether to use built-in helpers (required in Babel 7, removed in Babel 8+) */
  useBuiltIns: boolean;
  
  /** Whether to use spread syntax for props (removed in Babel 8+) */
  useSpread?: boolean;
}

Development Features

__source Attribute

Automatically added to all JSX elements to provide source location information for debugging.

interface SourceInfo {
  /** The filename where the JSX element is located */
  fileName: string;
  /** The line number of the JSX element */
  lineNumber: number;
  /** The column number of the JSX element */
  columnNumber: number;
}

__self Attribute

Provides reference to the current component instance (this) for debugging purposes, automatically added to all JSX elements.

Runtime Modes

Automatic Runtime

Uses the new JSX transform introduced in React 17. JSX elements are transformed to _jsx() calls:

{
  "plugins": [
    ["@babel/plugin-transform-react-jsx-development", {
      "runtime": "automatic"
    }]
  ]
}

Classic Runtime

Uses the traditional React.createElement approach:

{
  "plugins": [
    ["@babel/plugin-transform-react-jsx-development", {
      "runtime": "classic",
      "pragma": "React.createElement",
      "pragmaFrag": "React.Fragment"
    }]
  ]
}

Configuration Examples

Basic Development Setup

{
  "env": {
    "development": {
      "plugins": ["@babel/plugin-transform-react-jsx-development"]
    },
    "production": {
      "plugins": ["@babel/plugin-transform-react-jsx"]
    }
  }
}

Custom Import Source

{
  "plugins": [
    ["@babel/plugin-transform-react-jsx-development", {
      "importSource": "@emotion/react"
    }]
  ]
}

Pragma Comments

You can also control the JSX transform behavior using comments in your source files:

/** @jsx CustomReact.createElement */
/** @jsxFrag CustomReact.Fragment */
/** @jsxImportSource preact */
/** @jsxRuntime automatic */
<div>Hello</div>

Error Handling

The plugin will throw errors in the following cases:

  • JSX Namespace Usage: When throwIfNamespace is true (default) and JSX namespace syntax is used
  • JSX Spread Children: When JSX spread children syntax is used (not supported in React)
  • Runtime Conflicts: When importSource is set with runtime: "classic" or when pragma/pragmaFrag are set with runtime: "automatic"
  • Babel 8+ Option Removal: When deprecated options (useBuiltIns, useSpread) are used with Babel 8+
  • Filter with Automatic Runtime: When filter option is used with runtime: "automatic" in Babel 8+
  • Invalid Option Types: When boolean options receive non-boolean values
  • useBuiltIns and useSpread Conflict: When both useBuiltIns and useSpread are true in Babel 7 classic runtime

Compatibility

  • Node.js: >=6.9.0 (>=20.19.0 || >=22.12.0 for Babel 8)
  • Babel: ^7.0.0-0
  • React: All versions supporting JSX
  • TypeScript: Full support with type definitions included

Dependencies

  • Peer dependency: @babel/core (^7.0.0-0)
  • Direct dependency: @babel/plugin-transform-react-jsx (workspace dependency)

Architecture

This plugin is a simple wrapper that imports and re-exports the development version of the base JSX transform plugin from @babel/plugin-transform-react-jsx/lib/development. It inherits all functionality from the main JSX transform plugin while enabling development-specific debugging features:

  • Source Code Location: The actual transformation logic is implemented in @babel/plugin-transform-react-jsx with a development: true flag
  • Wrapper Pattern: This package provides a convenient entry point specifically for development builds
  • Shared Codebase: Uses the same core transformation logic as the production plugin but with additional debugging metadata