esbuild中文文档Transformation - JSX、JSX dev、JSX factory、JSX fragment、JSX import source、JSX side effects

哈喽，大家好！我是「励志前端小黑哥」，我带着最新发布的文章又来了！

老规矩，小手动起来~点赞关注不迷路！

esbuild简单介绍

esbuild为了突破JavaScript语言的瓶颈，采用了Go语言编写，构建速度与同代码量下的webpack对比提升在10倍以上，开创了构建工具性能的新时代。

它的中文文档，本人正在不断的更新完善中，欢迎大家关注阅读！

语法转换 Transformation

JSX

Supported by: Build and Transform

此选项告诉esbuild如何处理JSX语法。以下是可用选项：

• transform

此选项告诉esbuild使用通用转换将JSX转换为JS，该转换在许多使用JSX语法的库之间共享。每个JSX元素都被转换为JSX工厂函数，并将元素的组件作为第一个参数（或者将JSX片段作为第一个参数）。第二个参数是一个props数组（如果没有props，则为null）。出现的任何子元素都将成为第二个参数之后的附加参数。

如果您想在单个文件上进行配置，可以使用// @jsxRuntime classic注释来实现。这是esbuild遵循Babel JSX插件中的一个约定。

• preserve

使用这个选项将在输出文件中保留JSX语法，而不会将其转换为函数调用。JSX元素被视为一级语法，并且仍然受到其他设置（如minification 和property mangling）的影响。

请注意，这意味着输出文件不再是有效的JavaScript可执行代码。当您希望在打包后通过另一个工具转换esbuild输出文件中的JSX语法时，可以使用此功能。

• automatic

这种转换方式是在React 17+中引入的，对React来说非常特殊。它根据JSX import source自动生成import语句，并介绍了许多关于如何处理JSX语法的特殊情况。细节太复杂了，这里无法描述。有关更多信息，请阅读React关于他们新的JSX转换的文档。如果要启用此转换的开发模式版本，则需要额外启用JSX dev配置。

如果要按文件配置，可以使用// @jsxRuntime automatic注释。这是esbuild遵循Babel JSX插件中的一个约定。

以下是将JSX转换设置为preserve的示例：

$ echo '<div/>' | esbuild --jsx=preserve --loader=jsx

<div />;

JSX开发模式（JSX dev）

Supported by: Build and Transform

如果JSX转换已设置为automatic，那么启用此设置会使esbuild自动将文件名和源代码位置注入到每个JSX元素中。然后，您的JSX库可以使用这些信息来帮助调试。如果JSX转换被设置为非自动模式，那么此设置将不起任何作用。以下是启用此设置的示例：

$ echo '<a/>' | esbuild --loader=jsx --jsx=automatic
import { jsx } from "react/jsx-runtime";
/* @__PURE__ */ jsx("a", {});


$ echo '<a/>' | esbuild --loader=jsx --jsx=automatic --jsx-dev
import { jsxDEV } from "react/jsx-dev-runtime";
/* @__PURE__ */ jsxDEV("a", {}, void 0, false, {
  fileName: "<stdin>",
  lineNumber: 1,
  columnNumber: 1
}, this);

JSX工厂函数（JSX factory）

Supported by: Build and Transform

这个选项可以设置每一个JSX元素的调用函数。通常一个JSX表达式像下面这样：

<div>Example text</div>

如果使用React.createElement，会被编译为下面这种形式的函数：

React.createElement("div", null, "Example text");

你可以使用此配置项更改这个React.createElement函数。比如，使用函数h代替：

$ echo '<div/>' | esbuild --jsx-factory=h --loader=jsx
/* @__PURE__ */ h("div", null);

或者，如果你使用的是typescript，你可以再tsconfig.json中像下面这样配置一下，esbuild就会自动从配置中获取这个选项：

{
  "compilerOptions": {
    "jsxFactory": "h"
  }
}

如果要按文件配置，可以在文件中使用// @jsx h注释。注意，当JSX解析模式设置为automatic时，此选项是无效的。

JSX片段函数（JSX fragment）

Supported by: Build and Transform

这个选项可以设置每一个JSX片段的调用函数。通常一个JSX片段像下面这样：

<>Stuff</>

如果使用React.Fragment，会被编译为下面这种形式的函数：

React.createElement(React.Fragment, null, "Stuff");

你可以使用此配置项更改这个React.Fragment函数。比如，使用函数Fragment代替：

$ echo '<>x</>' | esbuild --jsx-fragment=Fragment --loader=jsx
/* @__PURE__ */ React.createElement(Fragment, null, "x");

或者，如果你使用的是typescript，你可以再tsconfig.json中像下面这样配置一下，esbuild就会自动从配置中获取这个选项：

{
  "compilerOptions": {
    "jsxFragmentFactory": "Fragment"
  }
}

如果要按文件配置，可以在文件中使用// @jsxFrag Fragment注释。注意，当JSX解析模式设置为automatic时，此选项是无效的。

JSX导入源（JSX import source）

Supported by: Build and Transform

如果JSX转换已设置为automatic，那么通过设置它可以更改esbuild从哪个库自动导入JSX的辅助函数。请注意，这只适用于React 17+特有的JSX转换。如果您将JSX导入源代码设置为your-pkg，那么该软件包必须至少公开以下export：

import { createElement } from "your-pkg"
import { Fragment, jsx, jsxs } from "your-pkg/jsx-runtime"
import { Fragment, jsxDEV } from "your-pkg/jsx-dev-runtime"

/jsx-runtime运行时和/jsx-dev-runtime运行时子路径是经过设计的，硬编码的，不能更改。jsx和jsxs导入在jsx开发模式关闭时使用，jsxDEV导入在jsx-dev模式打开时使用。React关于其新的jsx转换的文档中描述了这些导入的含义。无论JSX开发模式如何，当一个元素有一个prop队列，后面跟着一个key属性时，都会使用createElement导入，如下所示：

return <div {...props} key={key} />

以下是将JSX导入源设置为preact的示例：

esbuild app.jsx --jsx-import-source=preact --jsx=automatic

或者，如果您使用的是TypeScript，您可以通过将其添加到tsconfig.json文件中来配置TypeScript的JSX导入源，并且esbuild能自动获取它，而无需进行配置：

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact"
  }
}

如果您想在单独的每个文件控制此设置，您可以在每个文件中使用// @jsxImportSource your-pkg注释。如果还没有通过其他方式设置JSX转换，或者希望按文件设置，那么您可能还需要添加// @jsxRuntime automatic注释。

JSX副作用（JSX side effects）

Supported by: Build and Transform

默认情况下，esbuild假设JSX表达式是无副作用的，这意味着它们用/*@__PURE__*/注释进行注释，并且在打包过程中未使用时会被删除。这遵循了JSX对虚拟DOM的常见使用，并适用于绝大多数JSX库。然而，有些人编写的JSX库不具有此属性（特别是JSX表达式可能具有任意的副作用，并且在未使用时无法删除）。如果您正在使用这样的库，您可以使用此设置来告诉esbuild 某些JSX表达式有副作用：

esbuild app.jsx --jsx-side-effects

结语

笔者根据esbuild文档搭建了一套简洁的ts开发脚手架工程，编译速度非常快！脚手架还整合了eslint，另一篇文章还附带了调试教程，需要的朋友看这里：esbuild配合vscode搭建的ts开发环境，这编译速度，真香

另外，esbuild中文文档专栏，本人目前正在翻译整理，关注我，有最新的翻译文档会第一时间通知你！

（本文完）

励志前端小黑哥，全网唯一账号！
关注我，带你了解更多前端知识！