Add docs for plugin-transform-react-jsx-development (#2846)

* Add docs for plugin-transform-react-jsx-development * Update docs/plugin-transform-react-jsx.md Co-authored-by: Brian Ng <[email protected]> --------- Co-authored-by: Brian Ng <[email protected]>
docschina · Nov 9, 2023 · c41c5c1 · c41c5c1
1 parent 6ca818d
commit c41c5c1
Show file tree

Hide file tree

Showing 3 changed files with 128 additions and 1 deletion.
diff --git a/docs/plugin-transform-react-jsx-development.md b/docs/plugin-transform-react-jsx-development.md
@@ -0,0 +1,122 @@
+---
+id: babel-plugin-transform-react-jsx-development
+title: "@babel/plugin-transform-react-jsx-development"
+sidebar_label: transform-react-jsx-development
+---
+
+:::info
+This plugin is included in `@babel/preset-react`
+:::
+
+This plugin is a developer version of [`@babel/plugin-transform-react-jsx`](./plugin-transform-react-jsx.md). It is designed to provide enhanced validation error messages and precise code location information for debugging React apps. Note that this plugin is intended to be used in a development environment, as it generates significantly more outputs than the production build.
+
+If you are using [`@babel/preset-react`](./preset-react.md), it will be automatically enabled by the [`development`](./preset-react.md#development) option so you don't have to install it.
+
+## Example
+
+**In**
+
+```js title="input.jsx"
+const profile = (
+  <div>
+    <img src="avatar.png" className="profile" />
+    <h3>{[user.firstName, user.lastName].join(" ")}</h3>
+  </div>
+);
+```
+
+**Out**
+
+```js title="output.js"
+import { jsxDEV as _jsxDEV } from "react/jsx-dev-runtime";
+
+const _jsxFileName = "input.jsx";
+const profile = _jsxDEV("div", {
+  children: [
+    _jsxDEV("img", {
+      src: "avatar.png",
+      className: "profile",
+    }, undefined, false, { fileName: _jsxFileName, lineNumber: 3, columnNumber: 5 }, this),
+    _jsxDEV("h3", {
+      children: [user.firstName, user.lastName].join(" "),
+    }, undefined, false, { fileName: _jsxFileName, lineNumber: 4, columnNumber: 5 }, this),
+  ]},
+  undefined, false, { fileName: _jsxFileName, lineNumber: 2, columnNumber: 3 }, this
+);
+```
+
+## Installation
+
+```shell npm2yarn
+npm install --save-dev @babel/plugin-transform-react-jsx-development
+```
+
+## Usage
+
+### With a configuration file (Recommended)
+
+Without options:
+
+```json title="babel.config.json"
+{
+  "plugins": ["@babel/plugin-transform-react-jsx-development"]
+}
+```
+
+With options:
+
+:::babel8
+
+```json title="babel.config.json"
+{
+  "plugins": [
+    [
+      "@babel/plugin-transform-react-jsx-development",
+      {
+        "throwIfNamespace": false, // defaults to true
+        "runtime": "automatic", // defaults to autoamtic
+        "importSource": "custom-jsx-library" // defaults to react
+      }
+    ]
+  ]
+}
+```
+
+:::
+
+:::babel7
+
+```json title="babel.config.json"
+{
+  "plugins": [
+    [
+      "@babel/plugin-transform-react-jsx-development",
+      {
+        "throwIfNamespace": false, // defaults to true
+        "runtime": "automatic", // defaults to classic
+        "importSource": "custom-jsx-library" // defaults to react
+      }
+    ]
+  ]
+}
+```
+
+:::
+
+### Via CLI
+
+```sh title="Shell"
+babel --plugins @babel/plugin-transform-react-jsx-development script.js
+```
+
+### Via Node API
+
+```js title="JavaScript"
+require("@babel/core").transformSync("code", {
+  plugins: ["@babel/plugin-transform-react-jsx-development"],
+});
+```
+
+## Options
+
+It accepts the same options as [`@babel/plugin-transform-react-jsx`](./plugin-transform-react-jsx.md#options).
diff --git a/docs/plugin-transform-react-jsx.md b/docs/plugin-transform-react-jsx.md
@@ -8,6 +8,8 @@ sidebar_label: transform-react-jsx
 This plugin is included in `@babel/preset-react`
 :::
 
+This plugin generates production-ready JS code. If you are developing a React app in a development environment, please use [`@babel/plugin-transform-react-jsx-development`](./plugin-transform-react-jsx-development.md) for a better debugging experience.
+
 ## Example
 
 ### React Automatic Runtime

diff --git a/website/sidebars.js b/website/sidebars.js
@@ -165,7 +165,10 @@ module.exports = {
             type: "doc",
             id: "babel-preset-react",
           },
-          items: ["babel-plugin-transform-react-jsx"],
+          items: [
+            "babel-plugin-transform-react-jsx",
+            "babel-plugin-transform-react-jsx-development",
+          ],
         },
         {
           type: "category",