oxc-node

Run TypeScript directly in Node.js, powered by Oxc.

oxc-node adds module resolution and transformation hooks to Node. When Node loads a file, oxc-node resolves the import with oxc-resolver, transforms the source with Oxc, and returns JavaScript with an inline source map for Node to execute.

Node remains the runtime. oxc-node is not a JavaScript runtime, bundler, or type checker, and it does not write build output to disk.

What it supports

• TypeScript and TSX without a separate build step
• ESM and CommonJS, including .mts, .cts, .mjs, and .cjs
• JSX and selected TypeScript compiler options
• tsconfig.json path aliases and TypeScript-aware import resolution
• Imports such as ./file.js resolving to ./file.ts or ./file.tsx
• Source-mapped stack traces
• Node features and flags such as watch mode, the test runner, and the inspector

Type annotations are removed at runtime, not checked. Run a type checker separately when you need type safety.

CLI

Install the CLI in a project:

npm install --save-dev @oxc-node/cli

Run a TypeScript entry point:

npx oxnode ./src/index.ts

oxnode starts Node with the @oxc-node/core hooks and source maps enabled. Arguments are passed through to Node, so normal Node workflows continue to work:

npx oxnode --watch ./src/server.ts
npx oxnode --test
npx oxnode --inspect ./src/index.ts

Running oxnode without arguments starts the Node REPL. Use oxnode --node-help to print Node's help; oxnode --help prints help for the wrapper.

Node hook

If you do not need the wrapper CLI, install the core package:

npm install --save-dev @oxc-node/core

Register it with any Node command:

node --import @oxc-node/core/register ./path/to/entry.ts
node --import @oxc-node/core/register --test

The register entry point installs both the ESM loader hooks and a CommonJS transform hook.

Configuration

By default, oxc-node reads tsconfig.json from the current working directory. Set OXC_TSCONFIG_PATH to use a different file. TS_NODE_PROJECT is also supported and takes precedence when both variables are set.

The supported tsconfig.json options are used for resolution and transformation. These include path aliases, module and JSX settings, legacy decorators and decorator metadata, class-field semantics, and relative import extension rewriting.

The ESM loader does not transform files in node_modules by default. Set OXC_TRANSFORM_ALL=1 if ESM dependencies also need transformation.

Programmatic transformation

@oxc-node/core also exposes the native Oxc transformer:

import { OxcTransformer } from "@oxc-node/core";

const transformer = new OxcTransformer(process.cwd());
const output = await transformer.transformAsync("example.ts", "const answer: number = 42;");

console.log(output.source());
console.log(output.sourceMap());

The standalone transformer emits CommonJS. The registered loader preserves the module format selected for ESM files.

Sponsored By