Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
transformSync
✓ import { transformSync } from 'oxc-transform';
✗ const { transformSync } = require('oxc-transform');
While CommonJS `require` might work with transpilation, direct ESM import is recommended and idiomatic for the specified Node.js engine versions.
transform
✓ import { transform } from 'oxc-transform';
✗ const { transform } = require('oxc-transform');
The asynchronous `transform` function is useful for I/O-bound or concurrent scenarios.
isolatedDeclarationSync
✓ import { isolatedDeclarationSync } from 'oxc-transform';
✗ const { isolatedDeclarationSync } = require('oxc-transform');
Use this to generate TypeScript declaration files (.d.ts) conforming to --isolatedDeclarations.
TransformOptions
✓ import type { TransformOptions } from 'oxc-transform';
Import types separately for type-only usage in TypeScript.
This example demonstrates how to use `transformSync` to transpile TypeScript code to JavaScript and simultaneously generate a `.d.ts` declaration file with isolated declarations, including basic options for JSX and React.
import assert from "assert";
import { transformSync } from "oxc-transform";
const filename = "test.ts";
const sourceCode = "class A<T> { constructor(arg: T) { console.log(arg); } }";
// Transform TypeScript code to plain JavaScript and generate a declaration file
const { code, declaration, errors } = transformSync(filename, sourceCode, {
typescript: {
declaration: true, // Enable isolated declarations
jsxPragma: "React",
jsxPragmaFrag: "React.Fragment"
},
// Example: Enable more transformations if needed
react: {
runtime: "automatic",
development: true
}
});
// Log results for verification
console.log("Transformed Code:\n", code);
console.log("Declaration File:\n", declaration);
// Basic assertions
assert.equal(code.trim(), "class A { constructor(arg) { console.log(arg); } }");
assert.equal(declaration.trim(), "declare class A<T> {\n constructor(arg: T);\n}");
assert.equal(errors.length, 0, `Expected no errors, but got ${errors.length} errors.`);
console.log("Transformation successful!");
Debug
Known issues
breakingThe `oxc-transform` package now requires Node.js versions `>=20.19.0` or `>=22.12.0`. Older Node.js versions are not supported and will fail to load the native module.fixUpgrade your Node.js environment to a compatible version (e.g., Node.js 20.19.0+ or Node.js 22.12.0+).
affects: <20.19.0 || <22.12.0
breakingChanges in internal `oxc_span` crate may affect TypeScript type re-exports. Specifically, identity `FromIn` implementation for `Ident` and re-exports of string types from `oxc_span` were removed, and a `static_ident!` macro was added. If your project relied on specific internal types re-exported by `oxc-transform`'s type definitions, these might now be unavailable or altered.fixReview your TypeScript code for any direct or indirect reliance on types originating from `oxc_span` through `oxc-transform`. Update type imports or adjust type declarations as necessary to conform to the new definitions.
affects: >=0.125.0
Errors
Common errors & fixes
Error: The module '\path\to\node_modules\oxc-transform\index.node' was compiled against a different Node.js version. This version of Node.js cannot load modules compiled against Node.js API version X.
The `oxc-transform` native module was built for a different Node.js ABI version than the one currently running, typically due to Node.js version mismatch.
fixEnsure your Node.js version meets the `oxc-transform` requirements (`^20.19.0 || >=22.12.0`). If you have multiple Node.js versions, switch to the correct one using `nvm use` or similar version manager. You may need to reinstall `oxc-transform` to rebuild it against your current Node.js ABI: `npm rebuild oxc-transform` or `npm install`.
ReferenceError: require is not defined in ES module scope
Attempting to use CommonJS `require` syntax in an ES Module context (`type: "module"` in `package.json` or `.mjs` file) for `oxc-transform`.
fixUse ES Module `import` syntax. Change `const { transformSync } = require('oxc-transform');` to `import { transformSync } from 'oxc-transform';`. Audit
Dependencies
No dependency data recorded yet.