OXC Angular Compiler

A high-performance, Rust-based Angular compiler for Node.js. Provides both a standalone transformer and a Vite plugin for Angular applications.

Features

• Fast compilation - Rust-based implementation via NAPI-RS
• Vite integration - Full-featured Vite plugin with HMR support
• Template compilation - Angular template to JavaScript transformation
• Style encapsulation - ViewEncapsulation.Emulated support
• Cross-file elision - Type-only import detection and removal
• Drop-in replacement - Compatible API with @angular/compiler-cli

Installation

npm install @oxc-angular/compiler
# or
pnpm add @oxc-angular/compiler

Quick Start

Vite Plugin

// vite.config.ts
import { defineConfig } from 'vite'
import { angular } from '@oxc-angular/compiler/vite-plugin'

export default defineConfig({
  plugins: [
    angular({
      tsconfig: './tsconfig.json',
      sourceMap: true,
    }),
  ],
})

Standalone Transformer

import {
  transformAngularFile,
  compileTemplateSync,
  extractComponentUrlsSync,
} from '@oxc-angular/compiler'

// Transform an entire Angular file
const result = await transformAngularFile(sourceCode, 'app.component.ts', {
  sourcemap: true,
})

// Compile a template only
const template = compileTemplateSync('<div>{{ title }}</div>', 'AppComponent', 'app.component.ts')

API Reference

Package Exports

| Export | Description | | --------------------------- | ------------- | | @oxc-angular/compiler | Vite plugin | | @oxc-angular/compiler/api | Low level API |

Core Functions

Template Compilation

// Asynchronous
compileTemplate(
  template: string,
  componentName: string,
  filePath: string,
  options?: TemplateCompileOptions
): Promise<TemplateCompileResult>

Full File Transformation

transformAngularFile(
  source: string,
  filename: string,
  options?: TransformOptions,
  resolvedResources?: ResolvedResources
): Promise<TransformResult>

Component Metadata Extraction

// Extract templateUrl and styleUrls
extractComponentUrlsSync(
  source: string,
  filename: string
): ComponentUrls[]

Style Processing

// Apply ViewEncapsulation.Emulated
encapsulateStyle(
  css: string,
  componentId: string
): string

HMR Support

// Generate HMR update module
generateHmrModule(
  componentId: string,
  templateJs: string,
  styles: string[],
  declarationsJs: string,
  constsJs: string
): string

Transform Options

interface TransformOptions {
  // Output
  sourcemap?: boolean

  // Compilation mode
  jit?: boolean
  hmr?: boolean
  advancedOptimizations?: boolean
  useDomOnlyMode?: boolean

  // i18n
  i18nUseExternalIds?: boolean

  // Component metadata
  selector?: string
  standalone?: boolean
  encapsulation?: 'Emulated' | 'None' | 'ShadowDom'
  changeDetection?: 'Default' | 'OnPush'
  preserveWhitespaces?: boolean

  // Cross-file elision
  crossFileElision?: boolean
  baseDir?: string
  tsconfigPath?: string
}

Vite Plugin Options

interface AngularPluginOptions {
  // Project configuration
  tsconfig?: string
  workspaceRoot?: string

  // File filtering
  include?: string | string[]
  exclude?: string | string[]

  // Features
  sourcemap?: boolean
  hmr?: boolean
  jit?: boolean
  advancedOptimizations?: boolean
  useDomOnlyMode?: boolean
  zoneless?: boolean
  liveReload?: boolean

  // Style processing
  inlineStylesExtension?: string

  // File replacements
  fileReplacements?: Array<{
    replace: string
    with: string
  }>
}

Vite Plugin Architecture

The Vite plugin consists of three sub-plugins:

1. Transform Plugin - Transforms Angular TypeScript files
2. HMR Plugin - Handles hot module replacement for templates and styles
3. Styles Plugin - Processes and encapsulates component styles

HMR Routes

| Route | Description | | -------------------- | -------------------------------- | | /@ng/component/:id | Serves compiled template updates | | /@ng/styles/:id | Serves style updates |

Supported Angular Features

Templates

• Control flow (@if, @for, @switch, @defer)
• Property/attribute/class/style bindings
• Event bindings and two-way binding
• Template references and variables
• Content projection (ng-content)
• Structural directives

Components

• Standalone components
• Host bindings and listeners
• Input/Output decorators
• Query decorators (ViewChild, ContentChild, etc.)
• View encapsulation modes
• Change detection strategies

Styles

• Inline styles
• External styleUrls
• ViewEncapsulation.Emulated
• CSS attribute selector scoping

i18n

• External message IDs
• File-based naming

Platform Support

Pre-built binaries for:

| Platform | Architecture | | -------- | ----------------------- | | macOS | Apple Silicon (aarch64) | | macOS | Intel (x86_64) | | Windows | x86_64 | | Windows | aarch64 | | Linux | x86_64 (glibc) | | Linux | x86_64 (musl) | | Linux | aarch64 (glibc) | | Linux | aarch64 (musl) |

Requirements

• Node.js 20.19.0+ or 22.12.0+
• Vite 6.0.0+ (for Vite plugin)

Development

# Build native bindings
pnpm run build:native

# Build TypeScript
pnpm run build:ts

# Run tests
pnpm test

# Run E2E tests
pnpm run test:e2e

Build Features

| Feature | Description | | -------------------- | ----------------------------------- | | allocator | Use MiMalloc for better performance | | cross_file_elision | Enable cross-file import analysis |

# Build with all features
pnpm run build-dev --features allocator,cross_file_elision --release

Project Structure

napi/angular-compiler/
├── src/
│   └── lib.rs              # NAPI bindings (Rust)
├── core/                    # TypeScript utilities
│   ├── index.ts            # Main exports
│   ├── program.ts          # OxcNgtscProgram
│   ├── compiler.ts         # OxcAngularCompiler
│   └── config.ts           # Configuration reader
├── vite-plugin/            # Vite plugin
│   ├── index.ts            # Main plugin
│   ├── angular-jit-plugin.ts
│   └── angular-build-optimizer-plugin.ts
├── e2e/
│   └── compare/            # Comparison test runner
└── package.json

Related

• oxc - The Oxidation Compiler
• Angular - Angular framework
• @angular/compiler - Official Angular compiler