JSX

Oxc transformer 支持转换 JSX。

基本用法

import { transform } from "oxc-transform";

const result = await transform("App.jsx", sourceCode, {
  jsx: {
    runtime: "automatic", // 或 "classic"
    development: false, // 或 true
    throwIfNamespace: true, // 或 false
    pure: true, // 或 false
    importSource: "react",
    pragma: "React.createElement",
    pragmaFrag: "React.Fragment",
    refresh: false, // 见下文
  },
  // 转换 TSX 文件时：
  typescript: {
    jsxPragma: "React.createElement", // 与 `jsx.pragma` 相同值
    jsxPragmaFrag: "React.Fragment", // 与 `jsx.pragmaFrag` 相同值
  },
});

您也可以设置 jsx: 'preserve' 来禁用 JSX 转换。

Oxc transformer 也支持 JSX pragma 注释，这在 Babel 和 esbuild 中也有支持。Pragma 注释对于在每个文件基础上配置 JSX 选项非常有用。

Pragma 注释扫描

Oxc 只扫描出现在文件中第一条语句之前的注释来查找 JSX pragma。这意味着放置在函数、类内部或任何语句之后的 pragma 注释会被忽略。

// @jsx h  ← ✅ 此 pragma 被识别（在第一条语句之前）

import { h } from "preact";

// @jsx React.createElement  ← ❌ 此 pragma 被忽略（在第一条语句之后）
function App() {
  return <div />;
}

此行为与 TypeScript 和 SWC 一致，它们都将 pragma 扫描限制在前导注释。注意 Babel 和 esbuild 会扫描文件中的所有注释（以最后一个为准）。

运行时

默认使用自动运行时转换。此转换在 React 17+ 中引入。此转换会自动注入所需的 import 语句。

您也可以通过将 jsx.runtime 选项设置为 "classic" 来使用经典运行时转换。

// @jsxRuntime classic / // @jsxRuntime automatic 是通过 pragma 注释配置此选项的方式。

两种运行时的通用选项

开发转换

默认情况下，开发特定的转换被禁用。您可以通过将 jsx.development 选项设置为 true 来启用它们。

XML 命名空间标签名

默认情况下，如果使用 XML 命名空间标签名（例如 <foo:bar baz:qux="foobar" />），会抛出错误。虽然 JSX 规范允许这样做，但默认禁止，因为 React 的 JSX 目前不支持它们。您可以通过将 jsx.throwIfNamespace 选项设置为 false 来允许它们。

纯注解

默认情况下，JSX 元素会被标注纯注解。纯注解是标记表达式的注释，表示如果其返回值未被使用，可以安全地移除。但如果希望保留 JSX 元素，这可能不是期望的行为。您可以通过将 jsx.pure 选项设置为 false 来禁用此功能。

自动运行时特定选项

导入源

此选项指定 JSX 辅助函数的导入源。默认值是 "react"。

例如，如果您想使用 preact 包而不是 react，可以将 jsx.importSource 设置为 "preact"，然后可能会注入以下导入语句：

import { createElement } from "preact";
import { Fragment, jsxDEV } from "preact/jsx-dev-runtime";
import { Fragment, jsx, jsxs } from "preact/jsx-runtime";

// @jsxImportSource preact 是通过 pragma 注释配置此选项的方式。

经典运行时特定选项

Pragma

此选项指定转换 JSX 表达式时使用的函数名。它应该是限定名（例如 React.createElement）或标识符（例如 createElement）。此选项在 esbuild 中称为 jsxFactory。

// @jsx createElement 是通过 pragma 注释配置此选项的方式。

Pragma Fragment

此选项指定转换 JSX 片段时使用的函数名。它应该是有效的 JSX 标签名。此选项在 esbuild 中称为 jsxFragment。

// @jsxFrag Fragment 是通过 pragma 注释配置此选项的方式。

React Refresh

React Refresh（也称为 React Fast Refresh）为 React 组件在开发期间提供热重载能力。

用法

要启用 React Refresh 转换，设置 jsx.refresh 选项：

import { transform } from "oxc-transform";

const result = await transform("App.jsx", sourceCode, {
  jsx: {
    development: true,
    refresh: true,
    // 或...
    // refresh: {
    //   refreshReg: "$RefreshReg$",
    //   refreshSig: "$RefreshSig$",
    //   emitFullSignatures: true,
    // },
  },
});

配置选项

选项	类型	默认值	描述
refreshReg	string	"$RefreshReg$"	用于注册组件以进行刷新的函数名
refreshSig	string	"$RefreshSig$"	用于创建刷新签名的函数名
emitFullSignatures	boolean	false	是否发出完整签名以便更好地调试