Upstreaming TSRX to OXC

This page is for OXC maintainers and contributors evaluating whether .tsrx support belongs upstream, and for anyone who wants to attempt it. It maps what would transfer, what would have to be rewritten, and what upstream would have to open up first, against pinned revisions.

Nothing here has been submitted to OXC and nothing is scheduled. OXC for TSRX is an independent community project, not affiliated with or endorsed by VoidZero or the OXC team, and no maintainer interest is claimed. What ships today is one npm package owning the oxlint and oxfmt command names, which does not depend on any of this.

Four facts set up the rest:

• TSRX works by making a copy: a scan builds a temporary in-memory TSX version of a file, OXC parses that copy exactly once, and results map back onto the authored bytes. It is the shape of a Vite plugin transform, except the copy never reaches disk.
• The reusable core is one crate, crates/tsrx_syntax. Its one direct dependency is unicode-id-start = "1", a standalone Unicode table, not an OXC API.
• There is no fork. All twelve OXC dependencies sit behind crates/oxc_adapter at one exact commit pin.
• At the audited revision, OXC has no merged whole-file language hook that could load this front end. Audited 2026-07-16 against the pin, 8e0ed2e (opens in new tab), and then-current OXC main, 6fe866a (opens in new tab). Boundaries move, so a real proposal would repeat that audit.

Select a node to read what it is, or step the buttons through the order:

The reusable core#

crates/tsrx_syntax keeps its modules private and its public API small. Two ideas run through it: the copy, a temporary legal-TSX version OXC reads while your file is never touched, and mapping back, the return trip that puts OXC's output into TSRX and checks itself before anything is written.

What could move upstream#

The classification is the point, not the directory names. "Direct reuse" means the code and its tests could move with little conceptual change, not that a patch would compile as-is.

What OXC does not expose today#

Every route a third-party language would need is closed in the audited source:

The PartialLoader row matters most. It hands the linter one contiguous slice of a file, which suits a <script> block inside HTML. TSRX is not like that: the whole file becomes a copy in which some ranges are yours and some are placeholders the tool wrote, and the two have to stay told apart. Treating it as a partial-loader case would quietly lose accuracy.

Provider discovery patches, built locally#

A smaller question stands on its own: how would an OXC tool find out that a project installed a third-party language provider at all? The proposed answer is a static oxc.provider block, and three adoption patches exist as source. "Built, verified locally" means the patch was applied to a clone at a pinned revision, compiled, and run against tests.

The diffs live under docs/architecture/patches/, with the pinned revisions and the exact git apply commands. No source is vendored here.

The Oxlint one is the substantive patch, and it stays in JavaScript: it sits directly above the single lint(args, ...callbacks) call at the end of apps/oxlint/src-js/cli.ts, so nothing crosses into Rust. With no provider installed the wrapper is unchanged. With one, it sends the paths that provider claims to its binary in pass-through mode and takes the worst exit code, and in --lsp mode composes both language servers behind the editor's one stdio connection. See the calling convention. With node_modules/.bin deleted and every tool name shadowed on PATH, the released official OXC extension still found that patched wrapper by ordinary Node resolution and started the provider's language server, which proves the protocol implementable and nothing more.

Vite+ needs no patch of its own, because it resolves the oxlint package and runs bin/oxlint from it without reading file extensions, so patching the resolved wrapper reaches Vite+ users. That holds only while Vite+ pins one exact oxlint version, and the pinned number moves between Vite+ releases. tests/packaging/vite-plus-provider.test.mjs records which version, the rest of the measurements, and the limit of a JavaScript-only patch: a directory argument goes to the native walker and never enumerates provider extensions.

Landing order#

The order this proposal would suggest, if a maintainer first accepted reading a TSX copy as a starting design. None of it is scheduled or agreed to.

1. Prototype a private TSRX front end. Scanner, copy builder, mapping, and errors in an experimental crate, with ordinary JS and TS skipping all of it, measured for speed and memory before anything else.
2. Give Oxlint a real way to accept a copy. It needs your file path, the TSX copy, the full mapping, and the rules for when a fix is safe. PartialLoader cannot carry that.
3. Integrate one tool at a time. Oxlint diagnostics and fixes, then formatting. Only then should SourceType, FileKind, and the language server advertise .tsrx.
4. Decide about native AST nodes separately. First-class TSRX redesigns node types, visitors, semantic analysis, and the formatter. Hiding that inside a "parser support" patch would be dishonest.

Budgets any experiment has to keep#

Ordinary JS, JSX, TS, and TSX files skip TSRX work entirely. Beyond that, four budgets:

• a normal TSRX lint does one scan, one TSX copy, and one OXC parse;
• TSRX format does two structural scans, the authored one plus a cheap check that the result came back the same shape, and still one OXC parse;
• the scanner borrows your text and stores numbers rather than copying strings per node, and fixes and formatting check themselves before writing;
• moving a module upstream adds no new copies, parses, allocations, or dynamic dispatch without measurements and an agreed new budget.

Tests freeze the size of sixteen hot data records, and release benchmarks gate every stage. See the core performance contract and the acceptance matrix.

Reproducible evidence#

cargo test --locked -p tsrx_syntax --test architecture
cargo test --locked -p tsrx_syntax --all-targets
pnpm run benchmark:native-lint
pnpm run benchmark:native-format