oxc-parser

library0.126.0jsnpmunverified

The `oxc-parser` package provides a high-performance JavaScript and TypeScript parser with a Node.js API, currently at version 0.126.0. It's part of the broader Oxc project, known for its fast Rust-based tooling. The project exhibits a rapid release cadence, with frequent updates incorporating new features, bug fixes, and occasional breaking changes as seen in recent `crates_v` releases. Oxc Parser generates an AST that is fully conformant with the ESTree standard for JavaScript/JSX and `@typescript-eslint/typescript-estree` for TypeScript, with minor deviations for Stage 3 decorators and specific import syntax proposals (`import defer`, `import source`). A key differentiator is its 'Fast Mode,' which disables semantic error reporting by default for performance-critical scenarios, leaving error checks to downstream tools. It also offers WASM support and direct ESM information extraction, making it suitable for parser plugins and code transformation tasks.

type-stubs web-framework data serialization testing

npm install oxc-parser

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OXC-PARSER

oxc-parser

type-stubsjavascriptv0.126.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parseSync

✓ import { parseSync } from 'oxc-parser'

✗ const { parseSync } = require('oxc-parser')

The `oxc-parser` package is an ESM-first library. Use `import` syntax.

parse

✓ import { parse } from 'oxc-parser'

✗ import parse from 'oxc-parser/parse'

`parse` is a named export, not a default export. Use the asynchronous version for I/O-bound or concurrent tasks.

Visitor

✓ import { Visitor } from 'oxc-parser'

✗ const { Visitor } = require('oxc-parser')

Use the provided `Visitor` class for traversing the AST in an object-oriented pattern.

Program

✓ import type { Program } from '@oxc-project/types'

✗ import { Program } from 'oxc-parser'

AST types like `Program`, `Statement`, etc., are exported from `@oxc-project/types`, not directly from `oxc-parser`. Use `import type` for type-only imports.

This quickstart demonstrates synchronous parsing of TypeScript code, enabling semantic error checks, and then traversing the generated AST using a custom visitor to count statements, also showing access to ESM information.

import { parseSync, Visitor } from "oxc-parser"; import type { Statement, Program } from '@oxc-project/types'; const code = "const message: String = /* 🤨 */ 'Hello, Oxc!';\n console.log(message);"; // File extension is used to determine which dialect to parse source as (e.g., .js, .jsx, .ts, .tsx). const filename = "test.tsx"; const result = parseSync(filename, code, { sourceType: 'module', astType: 'ts', showSemanticErrors: true // Enable semantic checks for full error reporting }); if (result.errors.length > 0) { console.error('Parsing errors:', result.errors); } else { console.log('Successfully parsed AST:', result.program.type); // Example visitor to count statements class StatementCounter extends Visitor { statementCount = 0; visitStatement(node: Statement) { this.statementCount++; super.visitStatement(node); } } const counter = new StatementCounter(); counter.visitProgram(result.program as Program); console.log(`Total statements: ${counter.statementCount}`); console.log('ESM Info:', result.esm); }

Debug

Known issues

breakingThe underlying allocator's `Box` and `Vec` methods were renamed, which can affect highly-specialized integrations interacting with Oxc's internal memory management. Typical usage via the `oxc-parser` Node.js API is unlikely to be affected.

fix

Review any code that directly interacts with `oxc_allocator` if you're building custom plugins that expose these Rust-level details. For most users, no direct fix is required.

affects: >=0.126.0

breakingInternal string and span type handling changed, including the removal of `FromIn` implementation for `Ident` and re-exports of string types from `oxc_span`. New macros like `static_ident!` were introduced.

fix

If your code directly imported or relied on specific string or span types re-exported from `oxc_span` or used `FromIn` for `Ident`, you might need to adjust imports and type usage according to the latest Oxc crate API. Consult the Oxc changelog for specifics.

affects: >=0.125.0

gotchaBy default, `oxc-parser` operates in 'Fast Mode' with `showSemanticErrors: false`. This means it will not report common semantic errors like duplicate variable declarations (e.g., `let foo; let foo;`). It's optimized for environments where other tools handle semantic validation.

fix

To enable full semantic error reporting, pass `showSemanticErrors: true` in the `options` object to `parse` or `parseSync`. Ensure your build pipeline includes another linter or checker if you rely on Oxc's parser for semantic validation without this option.

affects: >=0.1.0

gotchaThe AST produced by `oxc-parser` deviates slightly from standard ESTree and TS-ESTree for certain bleeding-edge features like Stage 3 decorators and `import defer`/`import source` proposals. Ensure your tooling is compatible with these extensions if you rely on precise AST structure for these specific features.

fix

Refer to the Oxc documentation regarding AST deviations for Stage 3 features. Adapt any AST traversal or transformation logic that might be sensitive to these differences, particularly for `ImportExpression`'s `phase` field versus `CallExpression` structures.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: require is not a function

Attempting to use CommonJS `require()` syntax to import `oxc-parser` in an ESM context or a Node.js project configured for ESM.

fix

Change `const { parseSync } = require('oxc-parser');` to `import { parseSync } from 'oxc-parser';`. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions for ESM.

Property 'errors' does not exist on type 'ParseResult'.

This specific error message might not occur directly from `oxc-parser` because it does return an `errors` array. However, a common mistake is to assume all syntax issues are caught without enabling semantic errors or inspecting the errors array.

fix

Always check `result.errors` after parsing to identify any syntax or semantic issues. If semantic errors (like duplicate declarations) are expected but not found, ensure `showSemanticErrors: true` is passed to the parser options.

TypeError: Cannot read properties of undefined (reading 'type')

Accessing properties on an AST node that might be `undefined` or null, often because the parsing failed or a specific AST structure was not as expected.

fix

Always check for parsing errors (`result.errors`) before attempting to traverse or use the AST (`result.program`). Implement defensive checks (e.g., `if (node && node.type === '...')`) when traversing, especially with experimental syntax.

Upgrade

Version history

0.126.0latest on npm

Audit

Dependencies

@oxc-project/typesrequiredProvides TypeScript AST type definitions for better type safety and autocompletion when working with the parsed AST.

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/oxc-project/oxc ↗

packagehttps://www.npmjs.com/package/oxc-parser ↗

homepagehttps://oxc-project.github.io ↗