aphrody-labs/oxc
1
0 Fork 0
mirror of https://github.com/aphrody-labs/oxc.git synced 2026-10-14 22:29:17 +00:00
Code Issues Actions 11 Packages Projects Releases Wiki Activity

docs(transform-react): document all options (#25800)

Browse Source 
Documents the combined React transform pipeline and every supported transform, JSX, Fast Refresh, React Compiler, and environment option, including ESLint and Oxlint suppression comments.

Validation: Oxfmt, typos, and `git diff --check`.

AI-assisted.
This commit is contained in:
Boshen committed 2026-08-18 04:45:32 +00:00
1 parent f0121edb71
commit 627466ee8c
1 file changed
+186 -27
Download Patch File Download Diff File Expand all files Collapse all files
napi/transform-react/README.md
+186 -27
View File
@@ -1,10 +1,20 @@
# Oxc React Transform
# Oxc Transform React
Native Node.js bindings for Oxc's experimental Rust port of React Compiler.
Native Node.js bindings for Oxc's React transform pipeline. It combines:
The API follows `oxc-transform`: pass a filename, source text, and optional
options to either `transformSync` or `transform`. React Compiler runs first,
then Oxc removes TypeScript syntax and applies the configured JSX transforms.
- 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
```javascript
import { transformSync } from "oxc-transform-react";
@@ -16,14 +26,6 @@ const result = transformSync(
return <div>Hello {name}</div>;
}
`,
{
reactCompiler: {
target: "19",
},
jsx: {
runtime: "automatic",
},
},
);
if (result.fatal) {
@@ -33,22 +35,179 @@ if (result.fatal) {
}
```
`errors` contains every diagnostic reported by parsing, the React Compiler, and
the downstream transform. Recoverable React Compiler bail-outs are warnings;
compiler diagnostics retain error severity when `panicThreshold` makes the
transform fatal. Check `fatal` to decide whether the transform emitted usable
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.
`reactCompiler` defaults to `true`. Set it to `false` to skip React Compiler,
or pass an options object using the same names as
`babel-plugin-react-compiler`/`react-compiler-napi`, including
`compilationMode`, `panicThreshold`, `target`, `gating`, `outputMode`,
suppression controls, and the supported `environment` flags.
## API
`jsx` accepts the same options as `oxc-transform`, including automatic or
classic runtime configuration and React Fast Refresh. Set it to `"preserve"`
to leave JSX syntax in the output.
```typescript
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 appear in `errors` as
warnings while still producing code, so 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"`. |
| `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 files | Only run React Compiler when the filename contains one of the provided strings. |
| `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.
The object-valued target and gating options have these shapes:
```typescript
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` | `false` | 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 accepted by the native binding. `sources` accepts
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.
[React Compiler]: https://react.dev/learn/react-compiler
[`index.d.ts`]: https://github.com/oxc-project/oxc/blob/main/napi/transform-react/index.d.ts
[Oxc JSX documentation]: https://oxc.rs/docs/guide/usage/transformer/jsx