oxc-transform-react Copy package name

Oxc Transform React

Native Node.js bindings for Oxc's React transform pipeline. It combines:

• Oxc's experimental Rust port of React Compiler
• TypeScript syntax removal
• JSX transformation with automatic and classic runtimes
• React Fast Refresh
• These transforms can also be run individually

React Compiler runs first, then Oxc removes TypeScript syntax and applies the configured JSX and Fast Refresh transforms.

This package and Oxc's React Compiler port are experimental. Review generated output before using it in production.

Usage

import { transformSync } from "oxc-transform-react";

const result = transformSync(
  "Component.tsx",
  `
    export function Component({ name }: { name: string }) {
      return <div>Hello {name}</div>;
    }
  `,
);

if (result.fatal) {
  console.error(result.errors);
} else {
  console.log(result.code);
}

React Compiler is enabled by default with a React 19 target, and JSX uses the automatic runtime. Enable React Fast Refresh with jsx.refresh. The filename determines whether the input is parsed as JavaScript, JSX, TypeScript, or TSX.

API

transformSync(
  filename: string,
  sourceText: string,
  options?: TransformOptions,
): TransformResult;

transform(
  filename: string,
  sourceText: string,
  options?: TransformOptions,
): Promise<TransformResult>;

The asynchronous transform runs on a worker-pool thread. It is useful when processing files concurrently, but can be slower for a single small file.

TransformResult contains code, an optional source map, errors, and a fatal flag. Recoverable React Compiler bail-outs are omitted in every output mode, matching Babel's default logger: null. Fatal diagnostics appear in errors without producing code.

Options

All options are optional. Defaults in the tables below apply when a property is omitted.

Transform options

JSX options

refresh: true uses these defaults:

React Compiler options

Despite its upstream-compatible name, eslintSuppressionRules recognizes both ESLint and Oxlint comments: eslint-disable, eslint-disable-next-line, eslint-enable, oxlint-disable, oxlint-disable-next-line, and oxlint-enable.

outputMode: "ssr" takes precedence over noEmit. Otherwise, noEmit: true forces lint output, including when outputMode: "client" is set. Lint output suppresses only React Compiler rewrites; the downstream Oxc transform still removes TypeScript syntax and applies the configured JSX transform.

The object-valued target and gating options have these shapes:

interface ReactCompilerMetaTarget {
  kind: "donotuse_meta_internal";
  runtimeModule?: string; // Defaults to "react".
}

interface ReactCompilerGating {
  source: string;
  importSpecifierName: string;
}

interface ReactCompilerDynamicGating {
  source: string;
}

React Compiler environment options

Unset environment properties retain the compiler defaults shown here.

The default React 19 target imports react/compiler-runtime. Targets 17 and 18 import react-compiler-runtime, which must be available to the generated code.

Callback-valued options such as logger, function-valued sources, and type provider callbacks are not supported by the native binding. sources accepts an array of filename substrings instead.

Notes

• TypeScript support removes syntax only. It does not type-check or emit declarations.
• jsx.refresh emits Fast Refresh registration and signature instrumentation. The bundler or development server must provide the Refresh runtime and HMR integration.
• The transform stages are independent. reactCompiler: false still removes TypeScript and transforms JSX, while jsx: "preserve" retains JSX without disabling React Compiler. Recoverable compiler bail-outs still run the downstream TypeScript and JSX transforms.

See index.d.ts for the generated TypeScript declarations and the Oxc JSX documentation for more JSX examples.