oxc/napi/transform-react

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. Fatal diagnostics appear in errors without producing code. Recoverable React Compiler diagnostics are omitted by default; set reactCompiler.reportDiagnostics to include them in errors while code is still produced, and use fatal to determine whether the output is usable.

Options

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

Transform options

Option	Type	Default	Description
lang	string	Inferred from filename	Parse as "js", "jsx", "ts", "tsx", or "dts".
sourceType	string	Inferred	Parse as "script", "module", "commonjs", or "unambiguous".
sourcemap	boolean	false	Generate a source map in result.map.
jsx	"preserve" or JsxOptions	Automatic runtime	Configure the JSX transform. Set to "preserve" to leave JSX syntax in the output.
reactCompiler	boolean or ReactCompilerOptions	true	Configure React Compiler. Set to false to disable it or true to enable it with the default options.

JSX options

Option	Type	Default	Description
runtime	"classic" or "automatic"	"automatic"	Select the JSX runtime. The automatic runtime imports JSX factories; the classic one does not.
development	boolean	false	Emit development information such as __source and __self.
throwIfNamespace	boolean	true	Report an error for XML namespace syntax such as <svg:path>.
pure	boolean	true	Add pure annotations to JSX and top-level React calls for tree shaking.
importSource	string	"react"	Set the package imported by the automatic runtime.
pragma	string	"React.createElement"	Set the JSX factory used by the classic runtime.
pragmaFrag	string	"React.Fragment"	Set the JSX fragment used by the classic runtime.
refresh	boolean or ReactRefreshOptions	false	Enable React Fast Refresh, optionally with custom identifiers and signature output.

refresh: true uses these defaults:

Option	Type	Default	Description
refreshReg	string	"$RefreshReg$"	Set the Refresh registration identifier.
refreshSig	string	"$RefreshSig$"	Set the Refresh signature identifier.
emitFullSignatures	boolean	false	Emit readable hook signatures instead of compact hashes.

React Compiler options

Option	Type	Default	Description
compilationMode	string	"infer"	Select which functions to compile: "infer", "syntax", "annotation", or "all".
panicThreshold	string	"none"	Select which diagnostics abort the transform: "none", "critical_errors", or "all_errors".
reportDiagnostics	boolean	false	Include recoverable React Compiler diagnostics (skipped functions, rule suppressions, lint findings) in result.errors while still emitting code. Fatal diagnostics are always reported.
target	string or ReactCompilerMetaTarget	"19"	Target React "17", "18", "19", or a Meta-internal runtime.
gating	ReactCompilerGating	Unset	Emit compiled and original functions behind an imported feature flag.
dynamicGating	ReactCompilerDynamicGating	Unset	Resolve flags in "use memo if(...)" directives from an imported module. A directive takes precedence over gating.
noEmit	boolean	false	Request lint mode without applying React Compiler output. Deprecated; use outputMode: "lint".
outputMode	string	"client"	Select "client", "ssr", or "lint" React Compiler output.
eslintSuppressionRules	string[]	React Hooks rules	ESLint or Oxlint rule names whose matching suppression comments opt a function out. Defaults to react-hooks/exhaustive-deps and react-hooks/rules-of-hooks; [] disables this behavior.
flowSuppressions	boolean	true	Treat $FlowFixMe..., $FlowExpectedError, or $FlowIssue tags immediately followed by [react-rule as compiler opt-outs.
ignoreUseNoForget	boolean	false	Compile functions carrying "use no memo" or "use no forget".
customOptOutDirectives	string[]	Unset	Add directive strings that opt a function or module out of compilation.
sources	string[]	All except node_modules	Only run React Compiler when the filename contains one of the provided strings. Providing this option replaces the default filter.
environment	ReactCompilerEnvironmentOptions	Compiler defaults	Override compiler feature flags and validation settings.

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. Lint findings are recoverable diagnostics, so pair lint output with reportDiagnostics: true to receive them in errors.

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.

Option	Type	Default	Description
customMacros	string[]	Unset	Name macro-like functions whose calls and operands must stay together during compilation.
enableResetCacheOnSourceFileChanges	boolean	Unsupported	Accepted for upstream option compatibility but currently has no effect.
enablePreserveExistingMemoizationGuarantees	boolean	true	Use existing useMemo and useCallback information to preserve referential-equality behavior.
validatePreserveExistingMemoizationGuarantees	boolean	true	Validate that compilation preserves existing manual memoization guarantees.
validateExhaustiveMemoizationDependencies	boolean	true	Validate that manual memoization dependency arrays are exhaustive.
validateExhaustiveEffectDependencies	string	"off"	Validate effect dependencies with "off", "all", "missing-only", or "extra-only".
enableOptionalDependencies	boolean	Unsupported	Accepted for upstream option compatibility but currently has no effect.
enableNameAnonymousFunctions	boolean	false	Give generated or outlined anonymous functions inferred names.
validateHooksUsage	boolean	true	Validate that components partially satisfy the Rules of Hooks.
validateRefAccessDuringRender	boolean	true	Validate that ref values are not accessed during render.
validateNoSetStateInRender	boolean	true	Validate that state setters are not called unconditionally during render.
enableUseKeyedState	boolean	false	Recommend keyed state when reporting render-time state resets.
validateNoSetStateInEffects	boolean	false	In lint mode, validate that state setters are not called synchronously in effects.
validateNoDerivedComputationsInEffects	boolean	false	Validate that effects are not used to calculate data that can be derived during render.
validateNoDerivedComputationsInEffectsExp	boolean	false	In lint mode, enable the experimental form of derived-computation validation.
validateNoJsxInTryStatements	boolean	false	In lint mode, validate against creating JSX inside try blocks.
validateStaticComponents	boolean	false	In lint mode, validate against dynamically creating components during render.
validateNoCapitalizedCalls	string[]	Unset	Validate capitalized function calls. The array adds allowed names; [] enables validation without extra names.
validateBlocklistedImports	string[]	Unset	Bail out files that import any listed module.
validateSourceLocations	boolean	Unsupported	Accepted for upstream option compatibility but currently has no effect.
validateNoImpureFunctionsInRender	boolean	false	Validate against impure function calls during render.
validateNoFreezingKnownMutableFunctions	boolean	Unsupported	Accepted for upstream option compatibility, but validation currently runs regardless of its value.
enableAssumeHooksFollowRulesOfReact	boolean	true	Assume hook arguments and return values may be memoized and are therefore frozen.
enableTransitivelyFreezeFunctionExpressions	boolean	true	Treat values captured by functions passed to React as transitively frozen.
enableFunctionOutlining	boolean	true	Outline anonymous functions that do not capture local variables.
enableJsxOutlining	boolean	false	Outline nested JSX into separately memoizable components.
assertValidMutableRanges	boolean	Unsupported	Accepted for upstream option compatibility but currently has no effect.
enableCustomTypeDefinitionForReanimated	boolean	false	Use React Native Reanimated-aware type definitions.
enableTreatRefLikeIdentifiersAsRefs	boolean	true	Treat ref-like identifiers with a current property as React refs.
enableTreatSetIdentifiersAsStateSetters	boolean	false	Treat called identifiers whose names begin with set as state setters.
validateNoVoidUseMemo	boolean	false	Validate that useMemo callbacks return a value.
enableAllowSetStateFromRefsInEffects	boolean	true	Allow recognized ref-based state-setting patterns in effects.
enableVerboseNoSetStateInEffect	boolean	false	Emit more detailed diagnostics for state setters called in effects.
enableForest	boolean	false	Enable the experimental Forest reactive-scope optimization mode.

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.