oxc-node - GitLite

KO | EN

gitlite — search

#tensorflow #ai-agents #terminal #nodejs #developer-tools #deep-learning #linux #rag #awesome #security

oxc-node

(★ 227)

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

File Explorer

ZIP Download

- config.toml
- - autofix.yml
  - CI.yml
  - security.yml
- FUNDING.yml
- renovate.json
- pre-commit
- - index.ts
  - package.json
  - tsconfig.json
- - CHANGELOG.md
  - package.json
  - README.md
  - rolldown.config.js
  - tsconfig.json
- - condition-dev.ts
  - condition-node.mjs
  - condition-require.cjs
  - package.json
- - .gitignore
  - browser.js
  - CHANGELOG.md
  - esm.mjs
  - index.d.ts
  - index.js
  - oxc-node.wasi-browser.js
  - oxc-node.wasi.cjs
  - package.json
  - README.md
  - reexport-oxc-runtime.mjs
  - register.mjs
  - tsconfig.json
  - wasi-worker-browser.mjs
  - wasi-worker.mjs
- - package.json
  - tsconfig.json
- - package.json
  - tsconfig.json
- - package.json
  - tsconfig.json
  - vitest.config.ts
- lib.rs
.clippy.toml
.editorconfig
.gitattributes
.gitignore
.node-version
.rustfmt.toml
AGENTS.md
build.rs
Cargo.lock
Cargo.toml
CHANGELOG.md
justfile
lerna.json
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
rust-toolchain.toml
tsconfig.json
vite.config.ts

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`node`

View Details ▼

Server-side JavaScript platform (Node.js).

node {{path/to/file}}

Run a JavaScript file:

node

Start a REPL (interactive shell):

node --watch {{path/to/file}}

Execute the specified file restarting the process when an imported file is changed (requires Node.js version 18.11+):

🔍

`npm install`

View Details ▼

Install Node packages.

npm {{[i|install]}}

Install dependencies listed in `package.json`:

npm {{[i|install]}} {{package_name}}@{{version}}

Download a specific version of a package and add it to the list of dependencies in `package.json`:

npm {{[i|install]}} {{package_name}} {{[-D|--save-dev]}}

Download the latest version of a package and add it to the list of dev dependencies in `package.json`:

🔍

`npx`

View Details ▼

This command is an alias of `npm exec`.

tldr npm exec

View documentation for the original command:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![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 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:

```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.

## Node hook

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

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

Register it with any Node command:

```bash
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:

```js
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.

[ci-badge]: https://github.com/oxc-project/oxc-node/actions/workflows/CI.yml/badge.svg?branch=main
[ci-url]: https://github.com/oxc-project/oxc-node/actions/workflows/CI.yml
[npm-url]: https://npmx.dev/package/@oxc-node/core
[npm-badge]: https://img.shields.io/npm/dw/@oxc-node/core?label=npm

# [Sponsored By](https://oxc.rs/sponsor)

<p align="center">
  <a href="https://oxc.rs/sponsor">
    <img src="https://raw.githubusercontent.com/oxc-project/sponsors/main/sponsors.svg" alt="Our sponsors" />
  </a>
</p>