JSX

Oxc 트랜스포머는 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 트랜스포머는 JSX pragma 주석도 지원합니다. Babel 및 esbuild와 같습니다. 파일마다 JSX 옵션을 바꿀 때 유용합니다.

Pragma 주석 스캔

Oxc는 JSX pragma를 찾을 때 파일 첫 문장 앞에 있는 주석만 봅니다. 함수·클래스 안이나 어떤 문 뒤에 둔 pragma 주석은 무시됩니다.

// @jsx h  ← ✅ 인식됨 (첫 문장 전)

import { h } from "preact";

// @jsx React.createElement  ← ❌ 무시됨 (첫 문장 뒤)
function App() {
  return <div />;
}

이 동작은 TypeScript·SWC와 같으며, 선행 주석만 스캔합니다. Babel과 esbuild는 파일 내 모든 주석을 보고(마지막 값이 이김) 다르게 동작합니다.

런타임

기본은 automatic 런타임 변환입니다. React 17+에서 도입된 방식으로, 필요한 import를 자동으로 넣습니다.

jsx.runtime을 "classic"으로 두면 classic 런타임 변환을 씁니다.

pragma 주석으로는 // @jsxRuntime classic / // @jsxRuntime automatic을 사용합니다.

두 런타임 공통 옵션

개발용 변환

기본적으로 개발 전용 변환은 꺼져 있습니다. jsx.development를 true로 켭니다.

XML 네임스페이스 태그 이름

기본적으로 XML 네임스페이스 태그(예: <foo:bar baz:qux="foobar" />)가 있으면 오류를 냅니다. JSX 스펙상 허용되지만 React JSX가 아직 지원하지 않아 기본으로 금지합니다. jsx.throwIfNamespace를 false로 두면 허용합니다.

순수 주석

기본적으로 JSX 요소에 순수 주석이 붙습니다. 순수 주석은 반환 값이 쓰이지 않으면 안전히 제거할 수 있는 표현임을 표시합니다. JSX를 반드시 남겨야 한다면 jsx.pure를 false로 끕니다.

Automatic 런타임 전용 옵션

Import 소스

JSX 헬퍼 함수의 import 출처입니다. 기본값은 "react"입니다.

예: react 대신 preact를 쓰려면 jsx.importSource를 "preact"로 두면 다음과 같은 import가 들어갈 수 있습니다:

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

pragma 주석은 // @jsxImportSource preact입니다.

Classic 런타임 전용 옵션

Pragma

JSX 표현식 변환에 쓸 함수 이름입니다. 한정 이름(예: React.createElement)이나 식별자(예: createElement)여야 합니다. esbuild에서는 jsxFactory라고 부릅니다.

pragma 주석은 // @jsx createElement입니다.

Pragma Fragment

JSX 프래그먼트 변환에 쓸 함수 이름입니다. 유효한 JSX 태그 이름이어야 합니다. esbuild에서는 jsxFragment입니다.

pragma 주석은 // @jsxFrag Fragment입니다.

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	디버깅을 위해 전체 시그니처를 내보낼지 여부