OXC for TSRX

CLI Reference

Both native commands take explicit source files; directory walking and glob expansion belong to the oxc-tsrx npm toolchain and Vite+, not the native binaries. Any unsupported option is rejected with an actionable error rather than ignored.

What a plain install puts on your path#

npm install --save-dev oxc-tsrx@latest is the whole setup for the command line and for the editor. Vite+ needs one more command; see the minimum steps per host.

The install links seven commands into node_modules/.bin:

Command Kind What it is
oxlint you type it The linter. Sends .tsrx to the TSRX engine and everything else to canonical Oxlint.
oxfmt you type it The formatter, with the same split.
oxc-tsrx you type it providers, status, setup, remove. Described in the next section.
oxc-tsrx-lint leaf executor The native linter, given explicit files only. oxlint dispatches to it. It prints JSON, and it has no --help.
oxc-tsrx-fmt leaf executor The native formatter. oxfmt dispatches to it. --help works here.
oxc-tsrx-lsp leaf executor The native language server. Editors launch it through oxlint --lsp.
tsgolint not this project It arrives with the oxlint-tsgolint dependency, the official type-aware runner used by --type-aware and --type-check. You never call it directly, and calling it prints upstream's own "unsupported entrypoint" warning.

Reach for a leaf executor directly only when your project pins official oxlint or oxfmt, because those command names then belong to the pinned package.

The oxc-tsrx sections further down this page describe the native binary of the same name, which is what you get from a source build. It is a different program from the oxc-tsrx npm command above.

npx oxlint with no path also lints node_modules#

A bare npx oxlint walks the current directory, and node_modules is part of it unless something narrows the run. Measured in a scratch project made with npm init -y: 9260 warnings, 9257 of them from node_modules. Official Oxlint from the same install produces the same wall, so this is upstream parity and not something TSRX introduces.

A .gitignore containing node_modules removes it completely, with no git repository required, and naming a path (npx oxlint src) avoids it too. The same scope rule applies to --fix, which will rewrite files inside node_modules if you let it reach them. oxfmt is unaffected; it skips node_modules unless you pass --with-node-modules. There is more detail, with the measured numbers, in Getting Started.

oxc-tsrx (npm command)#

Usage: oxc-tsrx providers [--project <directory>] [--json]
       oxc-tsrx setup     [--project <directory>] [--dry-run] [--json]
       oxc-tsrx status    [--project <directory>] [--json]
       oxc-tsrx remove    [--project <directory>] [--dry-run] [--json]
Subcommand What it does
providers Reads the oxc.provider block of your direct dependencies and prints the index. It writes nothing and spawns nothing. routed extensions: .tsrx -> oxc-tsrx is the line that proves your install works.
setup Writes the project-local oxlint, oxfmt, and oxc-parser facades that Vite+ resolves, plus the editor slot below. Only Vite+ needs it.
status Reports whether those four slots are present.
remove Removes them and restores any transitive official package it displaced.

Run it with no subcommand for the same usage block. --help, -h, and help print it too, and --version, -V, and version print oxc-tsrx 0.1.3. A wrong subcommand names the bad word, prints the usage block after it, and exits 2.

The fourth slot is one key in .vscode/settings.json#

Three of the four slots are packages in node_modules. The fourth is the single setting oxc.path.oxlint, and it is the one thing setup writes into your own tree.

It exists because the official OXC extension finds its linter through node_modules/.bin/oxlint, and in a Vite+ project that shim belongs to Vite+, which knows nothing about .tsrx. Fixing package resolution does not fix that, so the editor went quiet with no error. setup writes "oxc.path.oxlint": "node_modules/oxc-tsrx/bin/oxlint" only when that shim does not already resolve into this package, merges it into whatever .vscode/settings.json you already have without disturbing another key or a comment, refuses to overwrite an oxc.path.oxlint you set yourself, and hands back exactly that one key on remove. package.json and tsconfig.json are never edited.

setup and status additionally report four TSRX editor prerequisites that belong to the TSRX toolchain and are never installed or changed here: @tsrx/typescript-plugin, a framework binding (@tsrx/react, @tsrx/vue, @tsrx/solid, @tsrx/preact, @tsrx/ripple, or octane), the nearest tsconfig.json declaring that plugin, and TypeScript at >=5.9 <6.

status says missing in a healthy project#

$ npx oxc-tsrx status
oxc-tsrx 0.1.3 compatibility (npm)
- oxc-parser: missing
- oxlint: missing
- oxfmt: missing
- oxc.path.oxlint: unnecessary (editor)
  …/node_modules/.bin/oxlint already resolves into this package, so the editor
  needs no setting and none was written.

That output is correct, and the exit code is 0. status only ever talks about the Vite+ compatibility slots, so missing means "not installed", which is the right state for every command-line and editor user, and unnecessary on the editor slot means the ordinary lookup already reaches this package. There is nothing to fix, and running setup is not the answer unless you use Vite+.

Use npx oxc-tsrx providers to check that TSRX support is actually wired up.

oxc-tsrx (lint)#

Usage: oxc-tsrx [OPTIONS] FILE...
Option Description
--format=json Emit JSON diagnostics. json is the only supported value in the current native CLI.
--config PATH, -c PATH Use an explicit JSON/JSONC Oxlint configuration; may be given once. Bypasses upward .oxlintrc.json/.oxlintrc.jsonc discovery.
--allow RULE, -A RULE Set a rule to allow (off), overriding configuration.
--warn RULE, -W RULE Set a rule to warn, overriding configuration.
--deny RULE, -D RULE Set a rule to deny (error), overriding configuration.
--fix Apply identity-only safe fixes to original TSRX bytes, each validated by a post-edit reparse before write.
--type-aware Opt into official tsgolint type-aware rules. Runs one TypeScript-Go process per batch over in-memory .tsrx.tsx virtual files; requires the supported oxlint-tsgolint executable.
--type-check Everything --type-aware does, plus TypeScript syntactic and semantic compiler diagnostics.
--config-base PATH Resolve a materialized config's relative paths (extends, ignores) against this directory. Used by the Vite+ host when the JSON payload lives in a disposable directory; requires --config.
--version Show the package version and canonical OXC revision.

At least one explicit source file is required. Files matching configured ignorePatterns are skipped.

Exit codes

Code Meaning
0 No errors, warning policy satisfied.
1 At least one error diagnostic, or options.denyWarnings/options.maxWarnings failed.
2 Usage, configuration, or engine error.

oxc-tsrx-fmt (format)#

Usage: oxc-tsrx-fmt [--write | --check] [--threads=INT] PATH...
       oxc-tsrx-fmt [--config=PATH] --stdin-filepath=PATH
Option Description
--write Format and write explicit files (default for files). Transactional: all reads and formats finish before any original is replaced.
--check Exit 1 and list files that differ; never write.
--stdin-filepath=PATH Read source from stdin, infer the source type from PATH, print formatted source to stdout.
--config PATH, -c PATH Use an explicit JSON/JSONC Oxfmt configuration. Bypasses upward .oxfmtrc.json/.oxfmtrc.jsonc discovery.
--threads=INT Worker count for explicit multi-file formatting.
-h, --help Show help.
-V, --version Show the package version and canonical OXC revision.

Exit codes

Code Meaning
0 Formatted successfully, or --check found no differences.
1 --check found files that differ.
2 Usage, configuration, or engine error.

oxc-tsrx-lsp (language server)#

The third binary hosts the same Rust lint and format sessions behind canonical OXC's language-server transport (stdio). It is launched by an editor client, not by hand. The public oxlint --lsp command starts it beside canonical Oxlint and dynamically registers .tsrx with the released official OXC extension. It provides live authored-span diagnostics, whole-document formatting, and validated quick fixes, with opt-in type-aware diagnostics. See Editor integration for architecture and proof commands.

npm direct upstream route#

The public oxlint and oxfmt commands from oxc-tsrx recognize a small set of canonical delegate flags. They also conservatively recognize explicit batches containing only existing ordinary JS/JSX/TS/TSX files. Those invocations load the pinned package's manifest-declared Oxlint or Oxfmt launcher in the same Node process instead of initializing the TSRX bridge:

Command Delegate-only flags
oxlint --help, -h, --version, -V, --rules, --init
oxfmt --help, -h, --version, -V, --init, --migrate, --lsp

This preserves canonical diagnostics, config/plugin loading, fixes, stdin, signals, and lifecycle behavior while avoiding a second process. Ambiguous paths, directories, globs, unknown options, and any .tsrx input remain on the TSRX-aware bridge.

oxlint --lsp is the deliberate exception. The public launcher multiplexes canonical Oxlint and oxc-tsrx-lsp: ordinary document traffic remains canonical, .tsrx traffic is routed to the native server, and both directions' request IDs are isolated. Ordinary non-LSP CLI invocations never enter this multiplexer.

Environment variables#

The oxc-tsrx toolchain's internal command packages locate native binaries through platform packages; during source development these overrides select release binaries explicitly:

Variable Description
OXC_TSRX_LINT_BIN Absolute path to the native oxc-tsrx binary.
OXC_TSRX_FORMAT_BIN Absolute path to the same native oxc-tsrx binary; the wrapper selects the formatter with its fmt subcommand.
OXC_TSRX_LSP_BIN Absolute path to the same native oxc-tsrx binary, used by the editor test harness during source development. The editor client starts it with lsp.

All three point at one executable. The linter, the formatter, and the language server are one native binary that dispatches on a leading subcommand (fmt, lsp, or lint, which is also the default) and on the name it was invoked under. Three separate binaries linked the same OXC engines three times.

A missing native artifact is an error; .tsrx is never silently delegated to stock tools.