OXC Angular Compiler

Warning

This project is in an experimental stage and is actively seeking maintainers.

Features

Installation

npm install @oxc-angular/vite
# or
pnpm add @oxc-angular/vite
# or
yarn add @oxc-angular/vite

Quick Start

Vite Plugin

// vite.config.ts

import { angular } from '@oxc-angular/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    angular({
      // Optional configuration
      angularVersion: { major: 21, minor: 0, patch: 0 },
      liveReload: true,
    }),
  ],
})

Programmatic API

import { compileTemplate, transformAngularFile } from '@oxc-angular/vite/api'

// Compile a template string
const result = await compileTemplate(
  '<div>{{ message }}</div>',
  'AppComponent',
  'app.component.ts',
  {
    angularVersion: { major: 21, minor: 0, patch: 0 },
    hmr: false,
  },
)

console.log(result.code)

// Transform an entire Angular file
const transformed = await transformAngularFile(
  `
  import { Component } from '@angular/core';

  @Component({
    selector: 'app-root',
    template: '<h1>Hello {{ name }}</h1>',
  })
  export class AppComponent {
    name = 'World';
  }
  `,
  'app.component.ts',
)

console.log(transformed.code)

API Reference

compileTemplate(template, componentName, filePath, options?)

transformAngularFile(source, filename, options?)

Transform Options

interface TransformOptions {
  // Angular version (19, 20, 21)
  angularVersion?: {
    major: number
    minor: number
    patch: number
  }

  // Enable Hot Module Replacement
  hmr?: boolean

  // Enable cross-file type elision
  crossFileElision?: boolean

  // i18n configuration (note the capital N, as the N-API bindings generate it)
  i18NUseExternalIds?: boolean

  // Style encapsulation mode
  // 'emulated' | 'none' | 'shadow-dom'
  encapsulation?: string
}

Architecture

HTML Template
      ↓
   PARSING        → HTML AST
      ↓
  TRANSFORM       → R3 AST (Angular's internal representation)
      ↓
  INGESTION       → Intermediate Representation (IR)
      ↓
TRANSFORMATION    → 67 optimization phases
      ↓
   EMISSION       → Output AST
      ↓
CODE GENERATION   → JavaScript

Core Modules

Platform Support

Requirements

Development

Prerequisites

Setup

# Clone the repository
git clone https://github.com/voidzero-dev/oxc-angular-compiler.git
cd oxc-angular-compiler

# Install dependencies
pnpm install

# Initialize submodules
git submodule update --init

# Build NAPI bindings
pnpm build

# Run tests
pnpm test

Development Commands

# Build (development)
pnpm build-dev

# Run Rust tests
cargo test

# Run Node.js tests
pnpm test

# Run E2E tests
pnpm test:e2e

# Run conformance tests against Angular
cargo run -p oxc_angular_conformance

# Start playground
pnpm playground

Project Structure

oxc-angular-compiler/
├── crates/
│   ├── oxc_angular_compiler/     # Core Rust compiler
│   └── angular_conformance/      # Conformance testing
├── napi/
│   └── angular-compiler/
│       ├── src/                  # NAPI bindings
│       ├── vite-plugin/          # Vite plugin (TypeScript)
│       ├── e2e/                  # E2E tests
│       └── test/                 # Integration tests
└── Cargo.toml                    # Rust workspace

Benchmarks

Bitwarden Web Vault (Cold Production Build)

Running Benchmarks

cd napi/angular-compiler/benchmarks/bitwarden

# Install dependencies
pnpm install

# Run full benchmark (cold + incremental, 3 iterations)
pnpm benchmark

# Cold build only
pnpm benchmark --cold

# Vite/OXC only (no baseline comparison)
pnpm benchmark --vite-only

# Custom iteration count
pnpm benchmark --iterations=5

Contributing

Related Projects

Acknowledgments