TypeScript Runner

Experimental

The TypeScript runner is experimental and under active development. APIs and behavior may change between releases.

oxc-node is Oxc's TypeScript runner. It runs TypeScript and JSX without a separate build step while preserving the standard Node.js command-line workflow.

The runner provides:

• The oxnode command for running scripts and starting a REPL.
• A Node.js register hook for use with node --import.
• Synchronous and asynchronous transformation APIs.
• ESM and CommonJS support.
• Source maps for stack traces.
• tsconfig.json integration.

CLI

Install @oxc-node/cli as a development dependency:

npm

$ npm add -D @oxc-node/cli

pnpm

$ pnpm add -D @oxc-node/cli

yarn

$ yarn add -D @oxc-node/cli

bun

$ bun add -D @oxc-node/cli

TIP

A project-local installation keeps the runner version consistent across your team. You can instead install @oxc-node/cli globally if you want to invoke oxnode outside a project or package script.

Run a TypeScript entry point:

oxnode ./src/index.ts

Arguments are passed through to Node.js, so Node.js features such as watch mode remain available:

oxnode --watch ./src/index.ts

Running oxnode without a script starts the Node.js REPL. Use oxnode --node-help to display Node.js command-line help.

For a repeatable project command, add a script to package.json:

package.json

{
  "scripts": {
    "dev": "oxnode ./src/index.ts"
  }
}

Node.js register hook

Install @oxc-node/core when you want to keep using the node command directly:

npm

$ npm add -D @oxc-node/core

pnpm

$ pnpm add -D @oxc-node/core

yarn

$ yarn add -D @oxc-node/core

bun

$ bun add -D @oxc-node/core

Register Oxc before loading the entry point:

node --import @oxc-node/core/register ./src/index.ts

Because this uses Node.js's register hook, it composes with other Node.js commands and flags. For example, run TypeScript tests with the built-in test runner:

node --import @oxc-node/core/register --test ./test.ts

Supported files

The register hook transforms the following extensions:

.js .jsx .ts .tsx .mjs .mts .cjs .cts .es6 .es

Module format is inferred from the file extension, the nearest package.json, and tsconfig.json. Files in node_modules are not transformed by default. Set OXC_TRANSFORM_ALL=1 to transform them as well.

TypeScript configuration

The runner reads tsconfig.json from the current working directory. Set OXC_TSCONFIG_PATH or TS_NODE_PROJECT to use a different file:

OXC_TSCONFIG_PATH=./config/tsconfig.dev.json oxnode ./src/index.ts

The transformer uses relevant compiler options for module format, JSX, decorators, class fields, and rewriting relative import extensions. TypeScript types are stripped during transformation; the runner does not type-check your program.

Links

• oxc-node repository
• @oxc-node/cli
• @oxc-node/core