ARCHITECTURE.md
Oxc (The Oxidation Compiler) is a collection of high-performance JavaScript and TypeScript tools written in Rust. The system is designed as a modular, composable set of compiler components that can be used independently or together to build complete toolchains for JavaScript/TypeScript development.
┌─────────────────────────────────────────────────────────────────┐
│ Applications │
├─────────────────────────────────────────────────────────────────┤
│ oxlint │ Language Server │ NAPI Bindings │ Future Tools │
├─────────────────────────────────────────────────────────────────┤
│ Core Libraries │
├─────────────────────────────────────────────────────────────────┤
│ Parser │ Semantic │ Linter │ Transformer │ Minifier │ Codegen │
├─────────────────────────────────────────────────────────────────┤
│ Foundation Libraries │
├─────────────────────────────────────────────────────────────────┤
│ AST │ Allocator │ Diagnostics │ Span │ Syntax │
└─────────────────────────────────────────────────────────────────┘
The system is built around an arena allocator (oxc_allocator) that enables zero-copy operations throughout the compilation pipeline. All AST nodes are allocated in a single arena, eliminating the need for reference counting or garbage collection.
AST traversal is implemented using the visitor pattern (oxc_ast_visit) with automatic visitor generation through procedural macros. This ensures type safety and performance while maintaining code clarity.
Common functionality like error reporting (oxc_diagnostics), source positions (oxc_span), and syntax definitions (oxc_syntax) are shared across all components to ensure consistency.
The Oxc AST differs significantly from the estree AST specification by removing ambiguous nodes and introducing distinct types. While many existing JavaScript tools rely on estree as their AST specification, a notable drawback is its abundance of ambiguous nodes that often leads to confusion during development.
For example, instead of using a generic estree Identifier, the Oxc AST provides specific types such as:
BindingIdentifier - for variable declarations and bindingsIdentifierReference - for variable referencesIdentifierName - for property names and labelsThis clear distinction greatly enhances the development experience by aligning more closely with the ECMAScript specification and providing better type safety.
oxc_parser → AST + commentsoxc_semantic → Symbol table + scope infoSource Text → Arena Allocator → AST Nodes → Visitors → Results
↓ ↓ ↓ ↓ ↓
UTF-8 Arena Borrowed Zero-copy Owned
String Memory References Processing Output
Decision: Use custom arena allocator instead of Rc/Arc Rationale:
Trade-offs:
Decision: Implement recursive descent parser instead of parser generator Rationale:
Trade-offs:
Decision: Use visitor pattern with procedural macros Rationale:
Trade-offs:
Correctness and reliability are taken extremely seriously in Oxc. We spend significant effort on strengthening the test infrastructure to prevent problems from propagating to downstream tools:
just --list for available commands)For detailed development guidelines, see CONTRIBUTING.md and AGENTS.md.
This architecture document follows the architecture.md format for documenting software architecture decisions and system design.