or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

@babel/preset-react

@babel/preset-react is a Babel preset that configures all the essential plugins needed for React development. It provides JSX transformation, development-specific debugging features, and optimization plugins in a single, comprehensive preset package.

Package Information

Package Name: @babel/preset-react
Package Type: npm
Language: TypeScript
Installation: npm install --save-dev @babel/preset-react

Core Imports

// As a Babel preset in babel.config.js
module.exports = {
  presets: ["@babel/preset-react"]
};

// With options
module.exports = {
  presets: [
    ["@babel/preset-react", {
      runtime: "automatic",
      development: true
    }]
  ]
};

For programmatic usage:

const presetReact = require("@babel/preset-react");

Basic Usage

// babel.config.js - Basic configuration
module.exports = {
  presets: ["@babel/preset-react"]
};

// With runtime configuration
module.exports = {
  presets: [
    ["@babel/preset-react", {
      runtime: "automatic", // Use React 17+ JSX transform
      development: process.env.NODE_ENV === "development"
    }]
  ]
};

// Classic runtime configuration
module.exports = {
  presets: [
    ["@babel/preset-react", {
      runtime: "classic",
      pragma: "React.createElement",
      pragmaFrag: "React.Fragment"
    }]
  ]
};

Architecture

The preset is built around several core components:

Preset Function: Main function created with declarePreset that configures React transformation plugins
Options Normalization: Comprehensive validation and default value handling via normalizeOptions
Plugin Configuration: Intelligent selection and configuration of React transformation plugins
Runtime Detection: Automatic switching between development and production transformation modes
Compatibility Layer: Support for both Babel 7 and Babel 8 with feature flags

Capabilities

Preset Configuration

The main preset function that configures all React transformation plugins.

/**
 * Main preset function that configures React transformation plugins
 * @param api - Babel API object with version assertion and environment methods
 * @param opts - Configuration options for the preset
 * @returns Preset configuration object with plugins array
 */
function presetReact(api: any, opts: Options): {
  plugins: Array<[Plugin, PluginOptions] | Plugin | false>;
};

Configuration Options

Complete configuration interface for customizing preset behavior.

interface Options {
  /** Enable development-specific transformations (default: false) */
  development?: boolean;
  /** Custom import source for JSX functions (default: "react" for automatic runtime) */
  importSource?: string;
  /** JSX pragma function name for classic runtime (default: "React.createElement") */
  pragma?: string;
  /** JSX fragment pragma for classic runtime (default: "React.Fragment") */
  pragmaFrag?: string;
  /** Pure annotation for tree-shaking optimization (default: true) */
  pure?: boolean;
  /** JSX transformation runtime mode */
  runtime?: "automatic" | "classic";
  /** Throw error on JSX namespaces (default: true) */
  throwIfNamespace?: boolean;
  /** Use built-in helpers (legacy, Babel 7 only) */
  useBuiltIns?: boolean;
  /** Use spread syntax (legacy, Babel 7 only) */
  useSpread?: boolean;
}

Runtime Modes

The preset supports two JSX transformation modes:

Automatic Runtime (React 17+)

Uses the new JSX transform that doesn't require React to be in scope:

// Configuration
{
  runtime: "automatic",
  importSource: "react" // default
}

// Input JSX
<div>Hello World</div>

// Output (production)
import { jsx as _jsx } from "react/jsx-runtime";
/*#__PURE__*/_jsx("div", { children: "Hello World" });

Classic Runtime (Legacy)

Uses the traditional React.createElement transform:

// Configuration
{
  runtime: "classic",
  pragma: "React.createElement", // default
  pragmaFrag: "React.Fragment"   // default
}

// Input JSX
<div>Hello World</div>

// Output
React.createElement("div", null, "Hello World");

Development Mode Features

When development: true or in development environment:

Uses @babel/plugin-transform-react-jsx-development for enhanced debugging
Adds filename and line number information to JSX elements
Provides better error messages and debugging experience

// Development output
var _jsxFileName = "/path/to/file.jsx";
import { jsxDEV as _jsxDEV } from "react/jsx-dev-runtime";
/*#__PURE__*/_jsxDEV("div", {
  children: "Hello World"
}, void 0, false, {
  fileName: _jsxFileName,
  lineNumber: 1,
  columnNumber: 1
}, this);

Plugin Configuration

The preset automatically configures these Babel plugins:

@babel/plugin-transform-react-jsx: Production JSX transformation
@babel/plugin-transform-react-jsx-development: Development JSX transformation
@babel/plugin-transform-react-display-name: Adds displayName to React components
@babel/plugin-transform-react-pure-annotations: Adds pure annotations for tree-shaking

Options Validation

Comprehensive options validation and normalization.

/**
 * Validates and normalizes preset configuration options
 * @param options - Raw options object from user configuration
 * @returns Normalized options with validated values and defaults
 */
function normalizeOptions(options: any): {
  development?: boolean;
  importSource?: string;
  pragma?: string;
  pragmaFrag?: string;
  pure?: string;
  runtime?: "automatic" | "classic";
  throwIfNamespace?: boolean;
  useBuiltIns?: boolean;
  useSpread?: boolean;
};

Usage Examples

Basic React Project

// babel.config.js
module.exports = {
  presets: ["@babel/preset-react"]
};

React 17+ with Automatic Runtime

// babel.config.js
module.exports = {
  presets: [
    ["@babel/preset-react", {
      runtime: "automatic"
    }]
  ]
};

Custom JSX Pragma

// babel.config.js - For custom JSX libraries
module.exports = {
  presets: [
    ["@babel/preset-react", {
      runtime: "classic",
      pragma: "h", // Use Preact's h function
      pragmaFrag: "Fragment"
    }]
  ]
};

Development vs Production

// babel.config.js
module.exports = {
  presets: [
    ["@babel/preset-react", {
      runtime: "automatic",
      development: process.env.NODE_ENV === "development"
    }]
  ]
};

Custom Import Source

// babel.config.js - For custom React implementations
module.exports = {
  presets: [
    ["@babel/preset-react", {
      runtime: "automatic",
      importSource: "@emotion/react" // Use Emotion's JSX
    }]
  ]
};

Error Handling

The preset provides comprehensive error handling and validation:

Version Compatibility: Requires Babel 7.0.0 or higher
Option Validation: Clear error messages for invalid configuration options
Runtime Validation: Validates runtime mode and suggests correct values
Babel 8 Migration: Helpful error messages for deprecated options in Babel 8

Common errors and solutions:

// Invalid runtime
{
  runtime: "invalid"
}
// Error: @babel/preset-react: 'runtime' must be one of ['automatic', 'classic']

// Babel 8 deprecated options
{
  useSpread: true
}
// Error: Since Babel 8, the "useSpread" option is no longer available