plugin-transform-react-jsx.md

Error in user YAML: (<unknown>): found character that cannot start any token while scanning for the next token at line 2 column 8

---
id: babel-plugin-transform-react-jsx
title: @babel/plugin-transform-react-jsx
sidebar_label: transform-react-jsx
---

Example

React Automatic Runtime

The automatic runtime is the default in v8.0.0. When enabled, the functions that Babel compiles JSX to are automatically imported.

In

const profile = (
  <div>
    <img src="avatar.png" className="profile" />
    <h3>{[user.firstName, user.lastName].join(" ")}</h3>
  </div>
);

Out

import { jsx as _jsx } from "react";
import { jsxs as _jsxs } from "react";

const profile = _jsxs("div", {
  children: [
    _jsx("img", {
      src: "avatar.png",
      className: "profile",
    }),
    _jsx("h3", {
      children: [user.firstName, user.lastName].join(" "),
    }),
  ],
});

Customizing the Automatic Runtime Import

In

/** @jsxImportSource custom-jsx-library */

const profile = (
  <div>
    <img src="avatar.png" className="profile" />
    <h3>{[user.firstName, user.lastName].join(" ")}</h3>
  </div>
);

Out

import { jsx as _jsx } from "custom-jsx-library";
import { jsxs as _jsxs } from "custom-jsx-library";

const profile = _jsxs("div", {
  children: [
    _jsx("img", {
      src: "avatar.png",
      className: "profile",
    }),
    _jsx("h3", {
      children: [user.firstName, user.lastName].join(" "),
    }),
  ],
});

In

/** @jsxRuntime classic */

const profile = (
  <div>
    <img src="avatar.png" className="profile" />
    <h3>{[user.firstName, user.lastName].join(" ")}</h3>
  </div>
);

Out

const profile = React.createElement(
  "div",
  null,
  React.createElement("img", { src: "avatar.png", className: "profile" }),
  React.createElement("h3", null, [user.firstName, user.lastName].join(" "))
);

React Classic Runtime

If you do not want (or cannot use) auto importing, you can use the classic runtime, which is the default behavior for v7 and prior.

In

const profile = (
  <div>
    <img src="avatar.png" className="profile" />
    <h3>{[user.firstName, user.lastName].join(" ")}</h3>
  </div>
);

Out

const profile = React.createElement(
  "div",
  null,
  React.createElement("img", { src: "avatar.png", className: "profile" }),
  React.createElement("h3", null, [user.firstName, user.lastName].join(" "))
);

Customizing the Classic Runtime Import

In

/** @jsx Preact.h */

import Preact from "preact";

const profile = (
  <div>
    <img src="avatar.png" className="profile" />
    <h3>{[user.firstName, user.lastName].join(" ")}</h3>
  </div>
);

Out

/** @jsx Preact.h */

import Preact from "preact";

const profile = Preact.h(
  "div",
  null,
  Preact.h("img", { src: "avatar.png", className: "profile" }),
  Preact.h("h3", null, [user.firstName, user.lastName].join(" "))
);

Fragments

Fragments are a feature available in React 16.2.0+.

React

In

const descriptions = items.map(item => (
  <>
    <dt>{item.name}</dt>
    <dd>{item.value}</dd>
  </>
));

Out

const descriptions = items.map(item =>
  React.createElement(
    React.Fragment,
    null,
    React.createElement("dt", null, item.name),
    React.createElement("dd", null, item.value)
  )
);

Customizing with the Classic Runtime

In

/** @jsx Preact.h */
/** @jsxFrag Preact.Fragment */

import Preact from "preact";

var descriptions = items.map(item => (
  <>
    <dt>{item.name}</dt>
    <dd>{item.value}</dd>
  </>
));

Out

/** @jsx Preact.h */
/** @jsxFrag Preact.Fragment */

import Preact from "preact";

var descriptions = items.map(item =>
  Preact.h(
    Preact.Fragment,
    null,
    Preact.h("dt", null, item.name),
    Preact.h("dd", null, item.value)
  )
);

Note that if a custom pragma is specified, then a custom fragment pragma must also be specified if the fragment sytnax <></> is used. Otherwise, an error will be thrown.

Installation

npm install --save-dev @babel/plugin-transform-react-jsx

Usage

With a configuration file (Recommended)

Without options:

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

With options:

{
  "plugins": [
    [
      "@babel/plugin-transform-react-jsx",
      {
        "throwIfNamespace": false, // defaults to true
        "runtime": "classic", // defaults to automatic
        "importSource": "custom-jsx-library" // defaults to react
      }
    ]
  ]
}

Via CLI

babel --plugins @babel/plugin-transform-react-jsx script.js

Via Node API

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

Options

Both Runtimes

throwIfNamespace

boolean, defaults to true.

Toggles whether or not to throw an error if an XML namespaced tag name is used. For example:

<f:image />

Though the JSX spec allows this, it is disabled by default since React's JSX does not currently have support for it.

You can read more about configuring plugin options here

runtime

classic | automatic, defaults to classic

Decides which runtime to use.

automatic auto imports the functions that JSX transpiles to. classic does not automatically import anything.

React Automatic Runtime

importSource

string, defaults to react.

Replaces the import source when importing functions.

React Classic Runtime

pragma

string, defaults to React.createElement.

Replace the function used when compiling JSX expressions.

Note that the @jsx React.DOM pragma has been deprecated as of React v0.12

pragmaFrag

string, defaults to React.Fragment.

Replace the component used when compiling JSX fragments.