oxc-project/oxc
⚓ A collection of high-performance JavaScript tools.
Parses, lints, formats, transforms, and minifies JavaScript/TypeScript code using Rust
Source code enters through either CLI applications or NAPI bindings and flows through a pipeline: parsing creates an AST, semantic analysis builds symbol tables and scope information, then specialized tools (linter, formatter, transformer, minifier) process the AST according to their configuration, finally codegen converts the potentially-modified AST back to JavaScript with optional source maps.
Under the hood, the system uses 2 feedback loops, 3 data pools, 4 control points to manage its runtime behavior.
A 9-component fullstack. 5293 files analyzed. Data flows through 7 distinct pipeline stages.
How Data Flows Through the System
Source code enters through either CLI applications or NAPI bindings and flows through a pipeline: parsing creates an AST, semantic analysis builds symbol tables and scope information, then specialized tools (linter, formatter, transformer, minifier) process the AST according to their configuration, finally codegen converts the potentially-modified AST back to JavaScript with optional source maps.
- Parse source code — Parser::new().parse() tokenizes JavaScript/TypeScript source and builds an AST with error recovery, detecting whether the source is a module or script based on file extension or explicit configuration
- Build semantic information — SemanticBuilder analyzes the AST to create symbol tables, resolve variable references, build scope chains, and detect binding relationships between identifiers [ParseResult → semantic data]
- Apply linting rules — Linter traverses the AST with semantic information to check for rule violations, applying configured rules from ESLint and custom rule sets to detect issues [Program → lint diagnostics]
- Transform syntax — Transformer modifies the AST to convert TypeScript to JavaScript, JSX to function calls, and modern syntax to compatible versions based on target environment configuration [Program → TransformOptions]
- Format code — Formatter traverses the AST to generate consistently formatted source code, applying spacing, indentation, and style rules without changing semantics [Program → formatted code string]
- Minify code — Minifier optimizes the AST by removing dead code, shortening variable names through mangling, and applying compression techniques to reduce bundle size [Program → optimized Program]
- Generate output code — Codegen::new().codegen() converts the final AST back to JavaScript source code, optionally generating source maps to maintain debugging information [Program → source code string]
Data Models
The data structures that flow between stages — the contracts that hold the system together.
npm/oxc-types/types.d.tsTypeScript interface with type: 'Program', body: Array<Directive | Statement>, sourceType: ModuleKind, hashbang: Hashbang | null
Created by Parser from source text, modified by transformers and semantic analysis, consumed by codegen and formatting
napi/parser/src/lib.rsRust struct containing program: Program, comments: Vec<Comment>, errors: Vec<OxcError>, and optional semantic data
Generated by Parser::parse(), passed through semantic analysis, converted to JavaScript objects via NAPI
napi/minify/src/lib.rsRust struct with mangle: Option<bool>, compress: Option<CompressOptions>, codegen: Option<Either<bool, CodegenOptions>>
Passed from JavaScript through NAPI, converted to internal MinifierOptions, used to configure Minifier behavior
napi/transform/src/lib.rsRust struct containing typescript: TypeScriptOptions, jsx: Option<JsxOptions>, es2015: Option<ES2015Options>
Provided by user, validated and converted to internal transform configuration, used by Transformer
oxc_napi crateJavaScript error object with message: string, line: number, column: number, severity: Severity
Created from Rust OxcDiagnostic during parsing/analysis, converted to JavaScript objects for user consumption
tasks/transform_conformance/src/test_case.rsRust struct with path: PathBuf, code: String, expected_code: Option<String>, config: TestConfig
Loaded from Babel test files, transformed by Oxc, compared against expected output for conformance validation
Hidden Assumptions
Things this code relies on but never validates. These are the things that cause silent failures when the system changes.
Native NAPI bindings (.node files) exist for the current platform/architecture combination and are compatible with the runtime Node.js version
If this fails: Silent failures when loading native modules on unsupported platforms, or crashes with cryptic 'module not found' errors that don't clearly indicate platform incompatibility
napi/*/index.js:requireNative
Parser, semantic analysis, and AST processing steps are executed in the exact order: parse -> semantic -> transform/format/minify, with each step consuming valid output from the previous step
If this fails: If steps are reordered or skipped, semantic information becomes stale, transformations operate on incorrect AST structure, and generated code contains wrong symbol references
napi/playground/src/lib.rs:Oxc::run_parser
The experimentalRawTransfer and experimentalLazy options are mutually exclusive - only one can be true at a time
If this fails: If both options are enabled, the function uses the first condition (experimentalRawTransfer) and ignores experimentalLazy, causing unexpected behavior when lazy deserialization was intended
napi/parser/src-js/index.js:parseSync
The babel submodule directory exists at tasks/coverage/babel with complete test fixtures and expected outputs available for reading
If this fails: Test runner crashes with file not found errors or produces incomplete conformance results when babel tests are missing or corrupted
tasks/transform_conformance/src/lib.rs:TestRunner::run
The 'ldd' command is available in PATH and execSync can successfully execute it to detect musl vs glibc
If this fails: Falls back to 'false' if ldd command fails, potentially loading wrong native bindings and causing crashes on musl-based Linux distributions like Alpine
napi/*/index.js:isMuslFromChildProcess
The source_text field remains valid and unchanged throughout the entire parsing/transformation pipeline lifetime
If this fails: If source text is modified after parsing but before error reporting, diagnostic messages show incorrect line/column positions or wrong source snippets
napi/playground/src/lib.rs:Oxc::source_text
The transformTestFilename function returns consistent results when called multiple times with the same filename input
If this fails: Test discovery becomes non-deterministic, causing tests to be included or excluded randomly between runs, making conformance results unreliable
apps/oxlint/conformance/src/index.ts:TestGroup::transformTestFilename
AST structures fit within JavaScript object size limits and don't exceed V8's maximum object property count (~16M properties)
If this fails: Large files with deeply nested ASTs cause out-of-memory errors or silent truncation when converting from Rust to JavaScript objects via NAPI
napi/playground/src/lib.rs:Oxc::ast
All TestGroup objects in the TEST_GROUPS array have valid submoduleName properties that correspond to actual directories in the submodules folder
If this fails: Conformance testing fails with path resolution errors when trying to locate test files for groups with invalid or mismatched submodule names
apps/oxlint/conformance/src/groups/index.ts:TEST_GROUPS
File extensions accurately indicate the language variant (.ts = TypeScript, .jsx = React, .vue = Vue) and parsing mode (module vs script)
If this fails: Files with non-standard extensions or content that doesn't match the extension get parsed with wrong syntax rules, leading to parse errors or incorrect AST structure
napi/playground/src/lib.rs:oxc_formatter::get_parse_options
System Behavior
How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.
Data Pools
Arena allocator that efficiently manages AST node memory with automatic cleanup, avoiding individual allocations for each node
Maps identifiers to their declarations, tracks variable scopes, and maintains binding information for semantic analysis
Stored expected outputs for conformance tests, updated when test behavior changes
Feedback Loops
- Error Recovery Loop (self-correction, balancing) — Trigger: Parser encounters syntax error. Action: Skip invalid tokens and attempt to resume parsing at next valid construct. Exit: End of input or successful parse recovery.
- Conformance Testing Loop (convergence, balancing) — Trigger: Test case failure in transform conformance. Action: Compare Oxc output against Babel expected result and record differences. Exit: All test cases processed or filter criteria met.
Delays
- Native Module Compilation (compilation) — NAPI bindings must be compiled for target platform before JavaScript can use Rust functionality
- Arena Allocation (warmup) — Initial memory allocation for AST arena happens before parsing can begin
Control Points
- Source Type Detection (architecture-switch) — Controls: Whether to parse as module or script, affecting available syntax features. Default: auto-detected from file extension
- Transform Target (architecture-switch) — Controls: Which JavaScript version to target, affecting which syntax transformations are applied. Default: configurable via TransformOptions
- Minification Level (threshold) — Controls: Aggressiveness of optimizations, balancing size reduction against safety. Default: configurable via MinifierOptions
- Error Recovery Mode (runtime-toggle) — Controls: Whether parser attempts to recover from errors or fails fast. Default: enabled by default
Technology Stack
Core implementation language providing memory safety and performance for parsing and transformations
Enables JavaScript bindings to Rust code without requiring Node.js version-specific compilation
Rust framework that simplifies creating N-API bindings with automatic JavaScript type generation
Provides type definitions for JavaScript APIs and implements conformance testing infrastructure
Manages dependencies across the monorepo workspace with efficient package linking
Next-generation bundler that uses Oxc for parsing and transformation
Key Components
- Parser (parser) — Parses JavaScript and TypeScript source code into AST nodes, handling both module and script parsing with error recovery
crates/oxc_parser/ - SemanticBuilder (processor) — Builds semantic information including symbol tables, scope chains, and reference resolution for the AST
crates/oxc_semantic/ - Linter (validator) — Applies configurable linting rules to detect code quality issues, style violations, and potential bugs
crates/oxc_linter/ - Formatter (transformer) — Formats JavaScript and TypeScript code according to configurable style rules, similar to Prettier
crates/oxc_formatter/ - Transformer (transformer) — Transforms TypeScript to JavaScript, JSX to regular JS calls, and modern syntax to compatible versions
crates/oxc_transformer/ - Minifier (optimizer) — Optimizes JavaScript code by removing dead code, shortening names, and applying compression techniques
crates/oxc_minifier/ - Codegen (encoder) — Converts AST back to JavaScript source code with optional source map generation
crates/oxc_codegen/ - TestRunner (orchestrator) — Orchestrates conformance testing by running Babel test cases through Oxc transformers and comparing outputs
tasks/transform_conformance/src/lib.rs - RuleTester (adapter) — Provides ESLint-compatible API for running linting rule tests, enabling validation against ESLint test suites
apps/oxlint/conformance/src/rule_tester.ts
Package Structure
A standalone formatter application that formats JavaScript and TypeScript code using Oxc's formatting engine.
A standalone linter application that analyzes JavaScript/TypeScript code for issues and includes conformance testing for ESLint compatibility.
Node.js package exposing Oxc's minification capabilities through NAPI bindings.
Node.js package providing JavaScript/TypeScript parsing with AST generation through NAPI bindings.
Interactive playground that combines all Oxc tools for experimentation and debugging.
Node.js package for TypeScript/JSX transformations and isolated declaration generation.
TypeScript type definitions for Oxc's AST nodes and data structures.
Runtime helper functions for transformed JavaScript code, similar to Babel helpers.
End-to-end testing framework with sample applications for validation.
Conformance testing suite that validates Oxc's transformations against Babel's test cases.
Generates browser compatibility data for ES features to guide transformations.
Explore the interactive analysis
See the full architecture map, data flow, and code patterns visualization.
Analyze on CodeSeaRelated Fullstack Repositories
Frequently Asked Questions
What is oxc used for?
Parses, lints, formats, transforms, and minifies JavaScript/TypeScript code using Rust oxc-project/oxc is a 9-component fullstack written in Rust. Data flows through 7 distinct pipeline stages. The codebase contains 5293 files.
How is oxc architected?
oxc is organized into 5 architecture layers: Core Libraries, CLI Applications, NAPI Bindings, NPM Distribution, and 1 more. Data flows through 7 distinct pipeline stages. This layered structure keeps concerns separated and modules independent.
How does data flow through oxc?
Data moves through 7 stages: Parse source code → Build semantic information → Apply linting rules → Transform syntax → Format code → .... Source code enters through either CLI applications or NAPI bindings and flows through a pipeline: parsing creates an AST, semantic analysis builds symbol tables and scope information, then specialized tools (linter, formatter, transformer, minifier) process the AST according to their configuration, finally codegen converts the potentially-modified AST back to JavaScript with optional source maps. This pipeline design reflects a complex multi-stage processing system.
What technologies does oxc use?
The core stack includes Rust (Core implementation language providing memory safety and performance for parsing and transformations), N-API (Enables JavaScript bindings to Rust code without requiring Node.js version-specific compilation), napi-rs (Rust framework that simplifies creating N-API bindings with automatic JavaScript type generation), TypeScript (Provides type definitions for JavaScript APIs and implements conformance testing infrastructure), pnpm (Manages dependencies across the monorepo workspace with efficient package linking), Rolldown (Next-generation bundler that uses Oxc for parsing and transformation). A focused set of dependencies that keeps the build manageable.
What system dynamics does oxc have?
oxc exhibits 3 data pools (AST Arena, Symbol Table), 2 feedback loops, 4 control points, 2 delays. The feedback loops handle self-correction and convergence. These runtime behaviors shape how the system responds to load, failures, and configuration changes.
What design patterns does oxc use?
4 design patterns detected: Arena Allocation, Visitor Pattern, NAPI Bridge, Conformance Testing.
Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.