Oxc Transform Node API

Common errors

• 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.

  cause 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.
  fix Ensure 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

  cause Attempting to use CommonJS `require` syntax in an ES Module context (`type: "module"` in `package.json` or `.mjs` file) for `oxc-transform`.
  fix Use ES Module `import` syntax. Change `const { transformSync } = require('oxc-transform');` to `import { transformSync } from 'oxc-transform';`.

Warnings

• breaking The `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.
  Fix: Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.19.0+ or Node.js 22.12.0+).
• breaking Changes 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.
  Fix: Review 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.

Install

• npm install oxc-transform npm
• yarn add oxc-transform yarn
• pnpm add oxc-transform pnpm

Imports

• transformSync
  wrong:

  const { transformSync } = require('oxc-transform');

  correct:

  import { transformSync } from 'oxc-transform';

  While CommonJS `require` might work with transpilation, direct ESM import is recommended and idiomatic for the specified Node.js engine versions.
• transform
  wrong:

  const { transform } = require('oxc-transform');

  correct:

  import { transform } from 'oxc-transform';

  The asynchronous `transform` function is useful for I/O-bound or concurrent scenarios.
• isolatedDeclarationSync
  wrong:

  const { isolatedDeclarationSync } = require('oxc-transform');

  correct:

  import { isolatedDeclarationSync } from '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.

Quickstart

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!");