vite-plugin-angular

A Vite plugin for building Angular applications. It handles Angular decorators, template compilation, the Ivy Linker, and Ahead-of-Time (AoT) compilation within the standard Vite build pipeline.

Benchmark

The following results were measured in an automated environment. Each tool was tested on the same Angular application under identical conditions. Results may vary depending on hardware and project size.

| Metric | Angular CLI | @analogjs/vite-plugin-angular | @ivanheral/vite-plugin-angular | | :--- | :---: | :---: | :---: | | Dev Cold Start | 3.83 s | 2.80 s | 722 ms | | Production Build | 4.57 s | 5.29 s | 3.09 s | | Bundle Size | 148.3 KB | 226.8 KB | 149.3 KB | | Direct Dependencies | — | 8 | 1 (magic-string) | | Plugin LOC | — | ~2,500 | ~600 |

Methodology: Cold start is measured as the time from process launch until the dev server reports "ready". Production build time is the full vite build duration. Bundle size is the uncompressed JS output.

Features

• Robust AST Parsing: Rewrites Angular decorators (@Component, @Directive, etc.) using the TypeScript Compiler API (AST) for comment-safe, string-safe extraction.
• Smart Compilation: Skips the slow TypeScript Compiler API transpilation for components without constructors, allowing esbuild to compile them natively (great for modern inject()-based DI).
• Native Styles Compilation: Integrates component stylesheets and inline styles with Vite's native PostCSS pipeline, enabling PostCSS, Tailwind CSS, and preprocessors in production component styles.
• Instant Styles HMR: Tracks and invalidates virtual inline styles directly in Vite's module graph when components are updated, providing instant style hot reloading.
• Ivy Linker: Applies the Angular Ivy Linker to pre-compiled libraries in node_modules via esbuild/rolldown.
• Ahead-of-Time (AoT): Supports AoT compilation for production builds with compile-time diagnostic verification.
• SSR Optimization: Defines ngServerMode statically to enable bundlers to tree-shake server-side code from browser bundles and vice versa.
• Angular Signals: Full JIT metadata injection for standard and required signals (input(), input.required(), model(), output(), viewChild(), etc.).
• High-Performance Caching: High-capacity true LRU memory cache (1024 items) and persistent disk-based caching for linker and optimizer transforms.
• HTML Minification: Minifies Angular HTML templates in production.
• Markdown & Pug: Supports templateUrl with Markdown (.md) and Pug (.pug) files.

Installation

# npm
npm install @ivanheral/vite-plugin-angular --save-dev

# pnpm
pnpm add @ivanheral/vite-plugin-angular -D

# yarn
yarn add @ivanheral/vite-plugin-angular --dev

# bun
bun add @ivanheral/vite-plugin-angular --dev

Usage

import { defineConfig } from 'vite';
import angular from '@ivanheral/vite-plugin-angular';

export default defineConfig({
  plugins: [
    angular()
  ]
});

For development with faster startups:

angular({
  fast: true,           // Skips template type-checking in dev mode
  styleInjection: 'inline'
})

For optimized production builds:

angular({
  aot: true,            // Enables AoT, removes @angular/compiler from the bundle
  minify: true
})

Configuration

| Option | Type | Default | Description | |---|---|---|---| | styleInjection | 'inline' \| 'global' | 'inline' | Controls how component stylesheets are injected. 'inline' preserves Angular's view encapsulation. 'global' enables faster CSS HMR. | | fast | boolean | false | Skips template type-checking during development for faster cold starts. | | fastMode | 'full' \| 'partial' | 'full' | Compiler output format. Use 'partial' when building reusable libraries. | | aot | boolean | false | Enables Ahead-of-Time compilation. Removes @angular/compiler from the production bundle. | | minify | boolean | true | Minifies HTML templates and CSS in production. | | tsconfigPath | string | auto | Path to the TypeScript config file. Defaults to tsconfig.app.json if present, otherwise tsconfig.json. | | jit | boolean | true | Controls whether JIT compiler imports are injected into the bootstrap file. | | zoneless | boolean | false | Disables zone.js injection. Detected automatically if provideExperimentalZonelessChangeDetection is found. |

fast

Disables template type-checking at dev time. The dev server starts in under 750 ms on most machines.

If you rely on template type safety, run it as a separate step:

{
  "scripts": {
    "type-check": "ngc -p tsconfig.app.json --noEmit",
    "build": "npm run type-check && vite build"
  }
}

aot

When set to true during a production build, the plugin runs the Angular compiler before Vite processes files. The compiled output is placed in node_modules/.cache/vite-plugin-angular/aot-out and deleted after the build. This removes @angular/compiler (~80 KB) from the final bundle.

If AoT compilation fails, the build is aborted immediately to prevent shipping a broken bundle.

Markdown & Pug Templates

The plugin passes through templateUrl values for .md and .pug files without appending ?raw, allowing other Vite plugins to process them:

@Component({
  selector: 'app-post',
  templateUrl: './post.component.md'
})
export class PostComponent {}

How It Works

1. Decorator transform: For each .ts file, the plugin uses the TypeScript Compiler API (AST) to rewrite templateUrl and styleUrls/styleUrl into static import statements that Vite can resolve and bundle normally.
2. Ivy Linker: Libraries published as partial Ivy (containing ɵɵngDeclare) are linked at dependency pre-optimization time using @babel/core and @angular/compiler-cli/linker/babel. Results are cached on disk.
3. AoT compilation: In production with aot: true, the Angular compiler runs via @angular/compiler-cli before Vite's transform phase, emitting JS files that replace the originals. If there are compile-time errors, the build is aborted immediately.
4. Constants: ngDevMode, ngJitMode, ngServerMode, and ngI18nClosureMode are set via config.define so Vite's minifier can eliminate dead code branches (particularly tree-shaking server/browser specific code).
5. Optimizer: If @angular/build's JavaScriptTransformer is available, it is applied to Angular packages in node_modules during production builds for additional optimizations.

License

MIT © Iván Hernández