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.
- TypeScript and TSX without a separate build step
- ESM and CommonJS, including
.mts,.cts,.mjs, and.cjs - JSX and selected TypeScript compiler options
tsconfig.jsonpath aliases and TypeScript-aware import resolution- Imports and
require()calls such as./file.jsresolving to./file.tsor./file.tsx. From JavaScript files and the entry point,./file.jsitself runs when it exists - Source-mapped stack traces
- Importing TypeScript from a tool, without hooks (
@oxc-node/core/importer) - 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.
Install the CLI in a project:
npm install --save-dev @oxc-node/cliRun a TypeScript entry point:
npx oxnode ./src/index.tsoxnode 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.tsRunning oxnode without arguments starts the Node REPL. Use
oxnode --node-help to print Node's help; oxnode --help prints help for the
wrapper.
There are two watch modes:
| Command | Watcher | Use it for |
|---|---|---|
oxnode watch ./src/server.ts |
oxnode's own | globs, Return to rerun, a kill timeout, polling |
oxnode --watch ./src/server.ts |
Node's --watch |
Node's own flags, such as --watch-path or --watch --test |
npx oxnode watch ./src/server.ts
npx oxnode watch --include "./config/*.json" --exclude "src/**/*.test.ts" ./src/server.ts --port 3000
npx oxnode watch --inspect --clear-screen=false ./src/index.tsoxnode watch [watch options] [node options] [--] <entry> [script args...]
└─────── before the entry ────────┘ └─ to the app ─┘
Write Node options as --flag=value. Everything after the entry goes to the
script, so --port 3000 above reaches the app.
The output looks like this:
16:14:24 [oxnode] watching for changes (Enter to rerun)
RUN v1
16:14:27 [oxnode] change in ./src/dep.ts, restarting
RUN v2
16:14:31 [oxnode] exited with code 1 — waiting for changes (Enter to rerun)
When the app exits or crashes, oxnode watch keeps watching and runs it again
on the next change.
| A change to | oxnode watch |
oxnode --watch |
|---|---|---|
| a file the app imports or requires | yes | yes |
tsconfig.json and every file it extends |
yes | yes |
a file that did not exist yet (x.ts for ./x.js) |
yes | yes, except Linux with Node 22/24 |
| a module loaded in a worker thread | Node 24+ | Node 24+ |
an --env-file file |
yes | yes |
a Node.js config file (--experimental-config-file) |
yes | no |
the --tsconfig file |
yes | (no such flag) |
a file matching --include |
yes, even if created later | use --watch-path |
a file in node_modules |
only with --include |
Node's rules |
a file matching --exclude |
no | (no such flag) |
Globs are relative to the current folder. An imported file counts only while the app imports it: before each rerun, oxnode forgets what the last run imported, as Node does.
These are the options from oxnode watch --help:
| Option | What it does |
|---|---|
--include <glob> |
Also watch files matching <glob> (repeatable; "!x" excludes) |
--exclude <glob> |
Never watch files matching <glob> (repeatable) |
--clear-screen=<bool> |
Clear the screen before each rerun (default: true, TTY only) |
--no-clear-screen |
Same as --clear-screen=false |
--kill-signal <signal> |
Signal that stops the app before a rerun (default: SIGTERM) |
--kill-timeout <ms> |
Force kill the app if it is still running after <ms> (default: 5000) |
--rerun-on-enter=<bool> |
Rerun when Return is pressed (default: true on a terminal) |
--no-rerun-on-enter |
Never read the terminal; the app keeps stdin to itself |
--poll[=<ms>] |
Poll files instead of using file system events (Docker, WSL, network drives) |
--tsconfig <path> |
Use this tsconfig (same as OXC_TSCONFIG_PATH) |
-h, --help |
Show this help |
--poll checks every 300 ms by default. --kill-timeout=0 force kills at
once. Setting CHOKIDAR_USEPOLLING=1 also turns on --poll.
For scripts moved from tsx, these also work:
| tsx flag | Same as |
|---|---|
--ignore <glob> |
--exclude <glob> |
--watch-preserve-output |
--no-clear-screen |
--watch-kill-signal <s> |
--kill-signal <s> |
--no-cache |
nothing (oxc-node has no cache) |
oxnode watch needs an entry file. It refuses --watch, --watch-path
(use --include), and -e, -p, -i, --test, --run and -. For tests,
use oxnode --watch --test.
| Key | While the app runs | While oxnode is stopping the app |
|---|---|---|
| Return | rerun now | force kill now |
| Ctrl+C | stop | press again to force kill |
A rerun first sends --kill-signal to the app. Once the app exits, oxnode
sends it to the processes the app started that are still running, and starts
the next run when they are gone, so a port they held is free again. If
anything is still running after --kill-timeout, oxnode kills it. A second
Ctrl+C counts only when it comes more than half a second after the first one.
| Case | oxnode, oxnode --watch |
oxnode watch |
|---|---|---|
| the app exits with a code | the same code | keeps watching |
| the app is killed by a signal | ends by the same signal (the shell sees 128+n) | keeps watching |
| the app dies by a core-dump signal | exits with 128+n, without its own core dump | keeps watching |
you stop oxnode (Ctrl+C, SIGTERM) |
the app's result, as above | the app's exit code if it had one, else 0 |
| you stop it while the app is not running | 0 | |
| the app cannot start | 1 | 1 |
| bad watch option, or no entry | 1 |
SIGINT, SIGTERM and SIGHUP sent to oxnode reach the app once. Ctrl+C
is not sent twice, and the second SIGINT that npm run sends is dropped.
Under oxnode --watch, SIGHUP is passed on as SIGTERM, because Node's
watcher ignores SIGHUP.
- Node 22 and worker threads. Modules loaded only in a worker thread are
not tracked. Add them with
--include. oxnode --watchon Linux with Node 22 or 24. Node's watcher cannot watch a file that does not exist yet, so creating a missing import does not restart. Useoxnode watch, or Node 26.- Docker, WSL (
/mnt/c) and network drives often send no file events. Use--poll. - Linux
ENOSPC. Raisefs.inotify.max_user_watches, or use--poll. - Globs need Node 22.5 or later.
- Return and stdin. On a terminal, oxnode and the app both read stdin, so a
line typed for the app can go to oxnode. If the app reads the terminal (a
prompt or a TUI), use
--no-rerun-on-enter. Piped stdin always goes to the app, unless you pass--rerun-on-enter. - Background jobs.
oxnode watch app.ts &does not read the terminal. A job moved to the background later (Ctrl+Z, thenbg) stops on its next read; use--no-rerun-on-enterfor that. - Processes left behind. On a rerun, oxnode stops what the app had started when the rerun began, and what those processes start later. A process the app starts while it is stopping, or leaves behind when it exits by itself, keeps running. Stop those in the app. A process even a force kill cannot stop (one stuck on a hung network drive, say) is left behind after 1 s.
- PID 1 in a container. Stopped processes stay as zombies, which oxnode
counts as gone. Use
docker run --initto clean them up. - Windows has no graceful stop before a rerun: oxnode ends the app and its
children at once, and
--kill-signalis ignored. - A script named
watch.oxnode watchis now the watch command, so run a file named exactlywatchasoxnode ./watch.
A tool with its own loader built on the oxc-node binding (Vite+'s vpx watch,
for example) can run the same watcher. Both sides have an entry:
your CLI the app (your loader)
runWatch(argv, options) ── node <loaderArgs> <node options> <entry> ──▶ installSignalAck()
@oxc-node/cli/watch watchSink(), withFlush()
◀── IPC { "watch:import": [url] } ────────────── @oxc-node/core/watch-report
◀── "I" on the OXNODE_SIGNAL_ACK socket ───────── @oxc-node/core/signal-ack
The watcher side:
import { runWatch } from "@oxc-node/cli/watch";
process.exitCode = await runWatch(process.argv.slice(2), {
name: "vpx watch",
loaderArgs: ["--enable-source-maps", "--require", preloadPath, "--import", hooksURL],
ignoreDirs: [loaderDir],
});| Option | Default | What it does |
|---|---|---|
loaderArgs |
["--enable-source-maps", "--import", "@oxc-node/core/register"] |
Node.js flags that load your hooks, put before the user's Node.js options |
ignoreDirs |
the folder of @oxc-node/core/register, if loaderArgs is not given, else none |
Folders of your loader's own files: Node.js reports them, but they are not watched |
name |
"oxnode watch" |
The command in errors, the usage line and --help; its first word tags the log lines ([vpx]) |
runWatch resolves with the exit code once the watcher stops. Until then it
handles SIGINT, SIGTERM, SIGHUP, stdin (Return) and the IPC channel of
the process, so add no handlers of your own and run one at a time. Importing
@oxc-node/cli/watch starts nothing, and it does not load clipanion or the
binding.
The app side, in your loader. take is your binding's
takeWatchDependencies, so these entries load no binding of their own:
import { isMainThread } from "node:worker_threads";
import { installSignalAck } from "@oxc-node/core/signal-ack";
import { watchSink, withFlush } from "@oxc-node/core/watch-report";
import { enableWatchReport, takeWatchDependencies } from "<your binding>";
if (isMainThread) installSignalAck(); // first, before the app's code
const sink = watchSink(); // once per thread; share it between your --require and --import
if (sink) enableWatchReport(); // before the first resolve or transform
const hooks = sink
? {
resolve: withFlush(resolve, sink, takeWatchDependencies),
load: withFlush(load, sink, takeWatchDependencies),
}
: { resolve, load };flush(sink, take) sends what the binding recorded, for code that is not a
hook (a CommonJS transform). createRelay(sink, take) returns a port for hooks
registered with module.register(), which run on a thread with no IPC.
From a CommonJS --require preload, require() of these two entries works on
Node.js 22.12 and later, as for @oxc-node/core/importer.
What the two sides agree on, for a loader that does not use these entries:
- Start. The app runs as
node <loaderArgs> <node options> <entry> <script args>with stdio["inherit", "inherit", "inherit", "ipc"], andWATCH_REPORT_DEPENDENCIES=1in its environment. - Reports. The app sends
{ "watch:import": [url] }(or"watch:require") over IPC. Each entry is afile:URL or an absolute path; a bad one is skipped alone. A report the loader makes itself (a tsconfig it read, a path a failed resolve looked for) also has"oxc-node": true: it counts even undernode_modules, and is dropped before each rerun. Other messages pass through both ways. - Ctrl+C. On POSIX,
OXNODE_SIGNAL_ACKnames a unix socket. While the app has aSIGINTlistener of its own, it writes the byteIto the socket for eachSIGINTit gets, and the watcher then does not send it a second one. The app removes the variable before its code runs. With no socket, or noI, the watcher passesSIGINTon as before.
OXNODE_WATCH_DEBUG, its output, and the log text are not part of this.
If you do not need the wrapper CLI, install the core package:
npm install --save-dev @oxc-node/coreRegister it with any Node command:
node --import @oxc-node/core/register ./path/to/entry.ts
node --import @oxc-node/core/register --testThe register entry point installs both the ESM loader hooks and a CommonJS transform hook.
By default, each file is governed by the nearest tsconfig.json in its own
ancestor directories that claims it through files, include, exclude or a
project reference — the same rule tsc follows. A file in a sub-project without
its own tsconfig.json therefore inherits the workspace root one, and a file
that no config claims is compiled with no options at all.
include only covers .js, .jsx, .mjs and .cjs files when allowJs is
enabled, so by default no config claims them and they are compiled with no
options. For module resolution they are matched as if they were TypeScript,
which keeps path aliases working from JavaScript without allowJs.
A tsconfig.json that fails to parse stops the search: that file and every
directory above it are skipped, and the file is compiled with no options.
Comments and trailing commas are fine — only genuinely invalid JSON does this.
Run with OXC_LOG=debug to see which config was picked for each file.
Set OXC_TSCONFIG_PATH to pin one config for every file instead. TS_NODE_PROJECT
is also supported and takes precedence when both variables are set; an empty value
counts as unset. Naming a file that does not exist disables tsconfig.json
handling entirely rather than falling back to the search above.
A tool that wraps the loader can name the config through the API instead, so the
choice does not leak into process.env and from there into the user's script and
the processes it spawns:
import { setTsconfigPath } from "@oxc-node/core";
setTsconfigPath("./tsconfig.app.json");
await import("@oxc-node/core/register");A path set this way takes precedence over both environment variables, and a
relative path resolves against the working directory, just as theirs does. The
config is read once per JavaScript thread, so call setTsconfigPath before the
first transform or resolve. On the asynchronous module.register() path, call it
before importing @oxc-node/core/register, which fixes the config for the hook
thread. Calling it later with a different path throws.
Each worker has independent configuration and resolver caches. A worker can select
a different tsconfig or clear its config variables without changing its parent.
The loader and programmatic transforms read the calling thread's process.env;
native asynchronous transforms carry that selection onto the task thread.
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.
A .ts, .tsx, .js or .jsx file with import/export syntax in a
"type": "commonjs" package is compiled to CommonJS when its tsconfig's module
is commonjs, node16, node18, node20 or nodenext, as tsc compiles it.
The output takes tsc's shape. An exported local is a plain, writable property of
exports, so mock.method(namespace, "name") replaces it for every CommonJS
importer, as it does under tsc. A local that is never reassigned is assigned once
it is declared; a reassigned one is exports.name itself, so it stays live, and
so is each binding of an export const [a, b] = … pattern. A re-export, and a
reassigned local exported under two names, declared by a pattern with a binding
that is not exported, or set to an anonymous function, stays live through a
getter instead, which a test cannot replace. In an import cycle, an export that has not
been set yet reads as undefined, as under tsc; function declarations are
exported before the file runs. A file's imports run before the rest of it, as in
an ES module.
The package must say "type": "commonjs": tsc also emits CommonJS for a package
without a "type", but there such a file runs as an ES module, as before, so a
project relying on Node.js' syntax detection keeps working. A file also stays an
ES module when it uses import.meta or top-level await, which have no CommonJS
form, or declares a value named like one the CommonJS wrapper or the compiled
output uses (exports, require, module, __filename, __dirname,
__importDefault, __importStar, __exportStar, Object, Symbol) at its top
level, or exports or a name starting with __vite_ssr_ anywhere, a parameter
included, or used as a global; a type of that name is fine. So does a file that
calls eval, which can read any local, and a top-level destructuring pattern
whose default is an anonymous function or class (const [f = () => 1] = []), or
whose binding a later assignment sets to one, as the function takes its name from
the binding. Removing "type": "commonjs" turns the compilation off.
It needs Node.js 22.22.3, 24.8 or later, where a file compiled to CommonJS can
require() one that stays an ES module. On earlier releases Node.js itself crashes
there, so every file runs as an ES module, as before.
Outside that combination — no "type", "type": "module", or an ES module
setting — a file with module syntax runs as an ES module, as before. A .cts
file is not compiled this way; see
Programmatic transformation.
With node16, node18, node20 or nodenext, the package's "type" decides the
format of a .ts or .tsx file without module syntax, as it does for tsc: in a
"type": "commonjs" package, or one without a "type", such a file is CommonJS,
also when an ES module imports it. Earlier releases ran it as an ES module. Only an
ES module setting, such as esnext, makes every .ts and .tsx file an ES
module.
An ES module that imports the compiled file gets what Node.js gives it for any CommonJS module:
- Its named imports are the names Node.js'
cjs-module-lexerfinds: the file's own exports, but not those it re-exports withexport *from another TypeScript file, because Node.js only follows re-exports into.jsand.cjsfiles. - Its default import is
module.exports, whosedefaultproperty is the file's default export: afterimport lib from "./lib.js", the classlib.tsexports as default islib.default. TypeScript types the import the same way undernodenext. Earlier releases ran the file as an ES module, whose default import was its default export. - Its imports are a snapshot taken when the file finishes loading, as for any
CommonJS module: a later write to an exported
letdoes not reach them. Earlier releases kept them live.
The compiled file's imports are require() calls. They resolve as its imports
did, with two differences:
- A dependency resolves with the
requirecondition, as undertsc, so a package whoseexportsoffers onlyimportfails withERR_PACKAGE_PATH_NOT_EXPORTED. An ESmodulesetting or"type": "module"keeps such a file an ES module. - Node.js caches a relative
require()per directory and request. When a JavaScript filerequire()s./lib.jsbefore a TypeScript file in the same directory does, both getlib.js, even next tolib.ts; when the TypeScript file asks first, both getlib.ts.
Otherwise TypeScript comes first, by the file's own name or by its output's:
./lib.js and ./lib find lib.ts, also when a compiled lib.js sits next to
it, ./lib.mjs finds lib.mts, and ./config finds config.ts before
config.json. When no lib.js exists, ./lib.js finds lib.jsx too. tsconfig
paths and baseUrl are tried before node_modules, and a package imports
entry or a self-reference that names output finds its source the same way. The
source is looked for beside the name a request reaches, before a symlink there is
followed. The
require() calls of every TypeScript file outside node_modules resolve this
way, and so do the extensionless ones of a .js file compiled from an ES module;
a file a package ships keeps its compiled .js. require.resolve() with a
paths option returns what Node.js finds in those directories.
Stack traces report the source's lines; for a file Node.js loads through the
module hooks — the entry point, or one an ES module imports — a column can be a
character off. Error messages and Function#toString show the compiled names of
imports, such as __vite_ssr_import_0__.
Importing an ES module — an .mts or .mjs file, or a "type": "module"
package — from the compiled file is require() of an ES module. Node.js loads the
entry point, test files and files an ES module imports through the module hooks,
together with the compiled files they require(), and require() of an ES module
from a file loaded that way needs
nodejs/node#59679, which the 22.x line
has from 22.22.3. Earlier releases fail with TypeError: Cannot read properties of undefined (reading 'exports').
The loader does not transform files in node_modules by default. Set
OXC_TRANSFORM_ALL=typescript to transform only the TypeScript dependencies —
.ts, .mts, .cts and .tsx; JavaScript dependencies are still left to
Node.js — or OXC_TRANSFORM_ALL=1 if every dependency needs transformation.
Absent, empty, 0 and false all keep dependencies untouched.
A tool that wraps the loader can choose through the API instead, so the choice
does not leak into process.env and from there into the user's script and the
processes it spawns:
import { setTransformDeps } from "@oxc-node/core";
setTransformDeps("typescript");
await import("@oxc-node/core/register");The setter accepts "typescript", "all" and "off" — the last keeps
dependencies untouched even when the variable asks for more. A mode set this
way takes precedence over OXC_TRANSFORM_ALL, and null
clears the override. The mode is read once per JavaScript thread, so call
setTransformDeps before the first transform or resolve; on the
module.register() path the deadline is the register import itself, which
fixes the mode for the hook thread. Calling it later with a different mode
throws. Native hook threads and WASI copies both receive the mode in effect when
@oxc-node/core/register is imported. Workers can choose different dependency
policies without changing each other.
OXC_TRANSFORM_ALL=typescript predates no older release: a version before
this one reads any non-empty, non-0/false value as transform-all, so if an
older copy is registered alongside (NODE_OPTIONS preloading a global install
is the common case) it transforms JavaScript dependencies too. The
setTransformDeps API is invisible to older copies and avoids that entirely.
@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.
A .cts file is CommonJS, so it cannot use ES module syntax (import, export,
or import.meta): oxc-node does not compile a .cts file's module syntax to
CommonJS the way tsc and tsx do, and the loader reports an error instead. Rename such a file to .mts, or write it
with import x = require() and export =. Type-only imports and exports are fine.
A tool that loads a user's config file, such as eslint.config.ts, can import
TypeScript without registering the hooks for the whole process.
@oxc-node/core/importer has the shape of jiti
v2:
import { createImporter } from "@oxc-node/core/importer";
const importer = createImporter(import.meta.url);
const config = await importer.import("./eslint.config.ts", { default: true });From CommonJS, require("@oxc-node/core/importer") works on Node.js 22.12 and
later.
createImporter(parentId, options)makes an importer that resolves fromparentId, a file path or afile:URL. A path that ends in/is a directory, and its owntsconfig.jsonapplies. The options aremoduleCacheandinteropDefault, bothtrueby default.importer.import(id, options)imports a module and returns a promise. Withdefault: trueit returns the default export, or the whole module when the default export is missing,nullorundefined(mod.default ?? mod, as in jiti).parentURLresolves from another file,conditionsreplaces the export conditions (["node", "import"]), andtry: truereturnsundefinedwhen the module is not found or its package does not export it.importer.resolve(id, options)returns afile:URL, or anode:id for a built-in module. It takesparentURL,conditionsandtrytoo.
The importer runs modules itself instead of through Node's loader, so nothing is
installed in the process: no loader hooks, no require.extensions, nothing in
require.cache, and process.sourceMapsEnabled stays as it is. Your own
import() and require() calls keep working as before. Inside the importer:
- Files are transformed as the loader transforms them, with the same
tsconfig.jsonlookup: path aliases, enums, legacy decorators, JSX, extensionless imports, JSON,.mts/.cts, top-level await. - A file is an ES module when its extension or
package.jsonsays so, or when it usesimport,export,import.metaor top-level await. Type-only imports and exports such asimport typedo not count. Other files run as CommonJS, even whentsconfig.jsonsets an ESmodule. - A CommonJS file can
require()an ES module file, as on newer Node.js. A module with top-level await throwsERR_REQUIRE_ASYNC_MODULEinstead. - Built-in modules,
@oxc-node/corehelpers and JavaScript files innode_modulesare loaded by Node itself. TypeScript files innode_modulesrun in the importer. - With
moduleCache: true, every importer in the process shares one module map, so each file runs once. Withfalse, everyimport()call runs your files again, which picks up edits; files Node loads stay in Node's own cache. interopDefaultcopies jiti: the properties of the default export can be read from the module too.- As in jiti,
__dirname,__filenameandrequirework in ES module files too, and an import of CommonJS that Babel ortsccompiled from an ES module (__esModule) gets itsexports.defaultas the default export. - A module that failed to load is tried again on the next
import(). A missing module fails withERR_MODULE_NOT_FOUND, orMODULE_NOT_FOUNDfromrequire(), and a path a package does not export withERR_PACKAGE_PATH_NOT_EXPORTED. - Each line of the output keeps the line number of its source where it can, so
stack traces point at the right TypeScript line. An error that escapes
import()also has its columns mapped back through the source map.
Differences from jiti:
- There is only the async
import(). jiti's synchronousjiti()call and options such asalias,fsCacheandtransformOptionsare not there; the transform is configured throughtsconfig.json, as for the loader. - The returned module is a plain object, not a real module namespace object.
import()insideevalornew Functionfalls back to Node's own loader, which does not transform TypeScript. Node may print an experimental warning the first time.
A tool that reloads a config after it changes, such as a migration tool or a linter in watch mode:
import { pathToFileURL } from "node:url";
import { createImporter } from "@oxc-node/core/importer";
export async function loadConfig(file) {
const url = pathToFileURL(file);
const importer = createImporter(url, { moduleCache: false });
return importer.import(url, { default: true });
}