oxc-project__oxc/crates/oxc/README.md

⚓ Oxc

The Oxidation Compiler is a high-performance web toolchain. This is an umbrella crate re-exporting all of oxc's different tools. It also adds higher-level APIs for stitching various components together that are not found in other oxc crates.

⚡️ Quick Start

The easiest way to get started with oxc is by adding this to your Cargo.toml:

[dependencies]
oxc = { version = "*", features = ["full"] }

In most cases, code using oxc will follow this general pipeline:

1. Parse source code into an AST
2. Run semantic analysis on the AST
3. Use the AST and semantic data in one or more other tools
4. Generate new code for the final processed program

Example

This example performs the first two steps of this pipeline:

use std::path::Path;

use oxc::{
    allocator::Allocator,
    parser::{Parser, ParserReturn},
    span::SourceType,
    semantic::{SemanticBuilder, SemanticBuilderReturn}
};

// In real code, this will likely come from a file read from disk.
let source_path = Path::new("test.tsx");
let source_text = "
import React from 'react';
export interface Props {
    count: number;
    onInc: () => void;
    onDec: () => void;
}
export const Counter: React.FC<Props> = props => {
    return (
        <div>
            <button onClick={props.onInc}>+</button>
            <span id='count'>{props.count}</span>
            <button onClick={props.onDec}>-</button>
        </div>
    );
};
";

// Memory arena where AST nodes are allocated.
let allocator = Allocator::default();
// Infer source type (TS/JS/ESM/JSX/etc) based on file extension
let source_type = SourceType::from_path(source_path).unwrap();
let mut errors = Vec::new();

// Step 1: Parsing
// Parse the TSX file into an AST. The root AST node is a `Program` struct.
let ParserReturn { program, diagnostics: parser_errors, fatal_error, .. } =
    Parser::new(&allocator, source_text, source_type).parse();
errors.extend(parser_errors);

// Parsing failed completely. `program` is empty and `errors` isn't. If the
// parser could recover from errors, `program` will be a valid AST and
// `errors` will be populated. We can still perform semantic analysis in
// such cases (if we want).
if fatal_error {
    for error in &errors {
        eprintln!("{error:?}");
        panic!("Parsing failed.");
    }
}

// Step 2: Semantic analysis.
// Some of the more expensive syntax checks are deferred to this stage, and are
// enabled using `with_check_syntax_error`. You are not required to enable
// these, and they are disabled by default.
let SemanticBuilderReturn {
    semantic,
    errors: semantic_errors,
} = SemanticBuilder::new()
    .with_check_syntax_error(true) // Enable extra syntax error checking
    .with_cfg(true)                // Build a Control Flow Graph
    .build(&program);              // Produce the `Semantic`

errors.extend(semantic_errors);
if errors.is_empty() {
    println!("parsing and semantic analysis completed successfully.");
} else {
    for error in errors {
        eprintln!("{error:?}");
        panic!("Failed to build Semantic for Counter component.");
    }
}

// From here, you can now pass `program` and `semantic` to other tools.

💡 Features

These feature flags enable/disable various tools in oxc's toolchain:

• full: Enable all features that provide access to a tool.
• semantic: Enable the semantic module for semantic analysis on ASTs.
• transformer: Enable the transformer module for babel-like transpiling.
• minifier: Enable the minifier and mangler modules for terser-like minification.
• codegen: Enable the codegen module, which prints ASTs to source code and source maps.
• mangler: Enable the mangler module without enabling minifier.
• cfg: Expose the cfg module. CFGs may still be created in semantic without turning this on.
• ast_visit: Enable the ast_visit module for AST traversal.
• regular_expression: Enable regular expression parsing support.
• isolated_declarations: enable the isolated_declarations module for generating typescript type declarations

These feature flags modify the behavior of oxc's tools. None of them are enabled by the full feature.

• serialize: Implements Serialize and Deserialize for various oxc data structures.
• conformance: Enables additional AST visitor hooks for conformance tests.