# `oxc-node` [![Build Status][ci-badge]][ci-url] [![npmjs.com][npm-badge]][npm-url] Run TypeScript directly in Node.js, powered by [Oxc](https://github.com/oxc-project/oxc). `oxc-node` adds module resolution and transformation hooks to Node. When Node loads a file, `oxc-node` resolves the import with [oxc-resolver](https://github.com/oxc-project/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 and `require()` calls such as `./file.js` resolving to `./file.ts` or `./file.tsx`. From JavaScript files and the entry point, `./file.js` itself 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. ## CLI Install the CLI in a project: ```bash npm install --save-dev @oxc-node/cli ``` Run a TypeScript entry point: ```bash 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: ```bash 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. ## Watch mode 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` | ```bash 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.ts ``` ``` oxnode watch [watch options] [node options] [--] [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. ### What restarts | 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. ### Options These are the options from `oxnode watch --help`: | Option | What it does | | ------------------------- | ---------------------------------------------------------------------------- | | `--include ` | Also watch files matching `` (repeatable; `"!x"` excludes) | | `--exclude ` | Never watch files matching `` (repeatable) | | `--clear-screen=` | Clear the screen before each rerun (default: true, TTY only) | | `--no-clear-screen` | Same as `--clear-screen=false` | | `--kill-signal ` | Signal that stops the app before a rerun (default: SIGTERM) | | `--kill-timeout ` | Force kill the app if it is still running after `` (default: 5000) | | `--rerun-on-enter=` | 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[=]` | Poll files instead of using file system events (Docker, WSL, network drives) | | `--tsconfig ` | 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 ` | `--exclude ` | | `--watch-preserve-output` | `--no-clear-screen` | | `--watch-kill-signal ` | `--kill-signal ` | | `--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`. ### Keys | 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. ### Exit codes and signals | 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`. ### Limits - **Node 22 and worker threads.** Modules loaded only in a worker thread are not tracked. Add them with `--include`. - **`oxnode --watch` on 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. Use `oxnode watch`, or Node 26. - **Docker, WSL (`/mnt/c`) and network drives** often send no file events. Use `--poll`. - **Linux `ENOSPC`.** Raise `fs.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, then `bg`) stops on its next read; use `--no-rerun-on-enter` for 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 --init` to clean them up. - **Windows** has no graceful stop before a rerun: oxnode ends the app and its children at once, and `--kill-signal` is ignored. - **A script named `watch`.** `oxnode watch` is now the watch command, so run a file named exactly `watch` as `oxnode ./watch`. ### Embedding the watcher 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 ──▶ 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: ```js 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: ```js 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 ""; 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