{"id":11513,"library":"oxc-transform","title":"Oxc Transform Node API","description":"oxc-transform is the Node.js API for Oxc's high-performance JavaScript, TypeScript, and React JSX transformer, which is built in Rust. It provides synchronous (`transformSync`, `isolatedDeclarationSync`) and asynchronous (`transform`, `isolatedDeclaration`) functions for parsing and transforming code. A key feature is its specialized capability for generating TypeScript declaration files (`.d.ts`) with isolated declarations, fully conforming to TypeScript's `--isolatedDeclarations` compiler option. Currently at version 0.126.0, the package maintains a rapid release cadence, reflecting active and continuous development within the broader Oxc project ecosystem. Its primary differentiators include its Rust-native performance, positioning it as a fast and efficient alternative to tools like Babel, and its robust, up-to-date support for modern ECMAScript features, TypeScript syntax, and React JSX out-of-the-box. The library is designed to serve as a foundational, high-performance component for various JavaScript build and tooling pipelines requiring efficient code transformation.","status":"active","version":"0.126.0","language":"javascript","source_language":"en","source_url":"https://github.com/oxc-project/oxc","tags":["javascript","babel","jsx","oxc","transform","transformer","tsx","typescript"],"install":[{"cmd":"npm install oxc-transform","lang":"bash","label":"npm"},{"cmd":"yarn add oxc-transform","lang":"bash","label":"yarn"},{"cmd":"pnpm add oxc-transform","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` might work with transpilation, direct ESM import is recommended and idiomatic for the specified Node.js engine versions.","wrong":"const { transformSync } = require('oxc-transform');","symbol":"transformSync","correct":"import { transformSync } from 'oxc-transform';"},{"note":"The asynchronous `transform` function is useful for I/O-bound or concurrent scenarios.","wrong":"const { transform } = require('oxc-transform');","symbol":"transform","correct":"import { transform } from 'oxc-transform';"},{"note":"Use this to generate TypeScript declaration files (.d.ts) conforming to --isolatedDeclarations.","wrong":"const { isolatedDeclarationSync } = require('oxc-transform');","symbol":"isolatedDeclarationSync","correct":"import { isolatedDeclarationSync } from 'oxc-transform';"},{"note":"Import types separately for type-only usage in TypeScript.","symbol":"TransformOptions","correct":"import type { TransformOptions } from 'oxc-transform';"}],"quickstart":{"code":"import assert from \"assert\";\nimport { transformSync } from \"oxc-transform\";\n\nconst filename = \"test.ts\";\nconst sourceCode = \"class A<T> { constructor(arg: T) { console.log(arg); } }\";\n\n// Transform TypeScript code to plain JavaScript and generate a declaration file\nconst { code, declaration, errors } = transformSync(filename, sourceCode, {\n  typescript: {\n    declaration: true, // Enable isolated declarations\n    jsxPragma: \"React\",\n    jsxPragmaFrag: \"React.Fragment\"\n  },\n  // Example: Enable more transformations if needed\n  react: {\n    runtime: \"automatic\",\n    development: true\n  }\n});\n\n// Log results for verification\nconsole.log(\"Transformed Code:\\n\", code);\nconsole.log(\"Declaration File:\\n\", declaration);\n\n// Basic assertions\nassert.equal(code.trim(), \"class A { constructor(arg) { console.log(arg); } }\");\nassert.equal(declaration.trim(), \"declare class A<T> {\\n    constructor(arg: T);\\n}\");\nassert.equal(errors.length, 0, `Expected no errors, but got ${errors.length} errors.`);\n\nconsole.log(\"Transformation successful!\");","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to a compatible version (e.g., Node.js 20.19.0+ or Node.js 22.12.0+).","message":"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.","severity":"breaking","affected_versions":"<20.19.0 || <22.12.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.125.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","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.","error":"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."},{"fix":"Use ES Module `import` syntax. Change `const { transformSync } = require('oxc-transform');` to `import { transformSync } from 'oxc-transform';`.","cause":"Attempting to use CommonJS `require` syntax in an ES Module context (`type: \"module\"` in `package.json` or `.mjs` file) for `oxc-transform`.","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm"}