README.md

angular-image-optimizer

Build-time image optimization for Angular. Generates multi-width WebP/AVIF variants at build time and wires them into Angular's NgOptimizedImage directive via a custom IMAGE_LOADER.

Installation

npm install angular-image-optimizer

The package ships three entry points:

Entry point	Contents
angular-image-optimizer/angular	provideImageOptimizerLoader() — Angular provider
angular-image-optimizer/esbuild	ngImageOptimizerEsbuild() — esbuild plugin

Setup with esbuild (Angular CLI)

1. Install @angular-builders/custom-esbuild

npm install -D @angular-builders/custom-esbuild

2. Switch builders

In angular.json, replace the build and serve builders:

"build": {
  "builder": "@angular-builders/custom-esbuild:application",
  "options": {
    "plugins": ["./plugins.js"]
  }
},
"serve": {
  "builder": "@angular-builders/custom-esbuild:dev-server",
  "options": {
    "prebundle": {
      "exclude": ["angular-image-optimizer"]
    }
  }
}

Nx users: use "executor" instead of "builder" in project.json.

3. Register the plugin

Create plugins.js at the project root:

import { ngImageOptimizerEsbuild } from 'angular-image-optimizer/esbuild';

export default [
  ngImageOptimizerEsbuild({
    include: ['src/assets/**/*.{jpg,jpeg,png}'],
  }),
];

4. Provide the image loader

In app.config.ts:

import { provideImageOptimizerLoader } from 'angular-image-optimizer/angular';

export const appConfig: ApplicationConfig = {
  providers: [provideImageOptimizerLoader()],
};

---

Using NgOptimizedImage in templates

<!-- Fixed size -->
<img ngSrc="hero.jpg" width="960" height="640" placeholder />

<!-- Fill mode -->
<div style="position:relative; aspect-ratio:3/2">
  <img ngSrc="hero.jpg" fill priority placeholder alt="Hero" />
</div>

<!-- Responsive with sizes -->
<img ngSrc="hero.jpg" width="960" height="640" sizes="(max-width: 960px) 100vw, 50vw" placeholder alt="Hero" />

The ngSrc value must match the image filename relative to the glob base (e.g. src/assets/hero.jpg → hero.jpg).

Plugin options

All options are optional.

Option	Type	Default	Description
include	string[]	['src/assets/**/*.{jpg,jpeg,png}']	Glob patterns (relative to project root) for source images
widths	number[]	[320, 640, 960, 1280, 1920]	Pixel widths to generate for each image
formats	('webp' | 'avif')[]	['webp']	Output formats to generate
quality	{ webp?: number; avif?: number }	{ webp: 85, avif: 80 }	Per-format encoding quality
outputDir	string	'assets/optimized'	Output directory within the build output / public dir

Troubleshooting

Could not resolve "virtual:ng-image-manifest" during ng serve

Angular's Vite dev server pre-bundles dependencies with its own esbuild instance, which does not include the ngImageOptimizerEsbuild plugin. When it scans angular-image-optimizer/angular, it finds the virtual:ng-image-manifest import and fails.

Fix: exclude angular-image-optimizer from Vite's pre-bundler so Angular's esbuild step (which does have the plugin) handles it instead. Add prebundle.exclude to the serve target — see step 2 above.

---

Development

# Build & test the library
npx nx build angular-image-optimizer
npx nx test angular-image-optimizer

# Serve demo apps
npx nx serve image-optimizer/demos/esbuild
npx nx serve image-optimizer/demos/esbuild-ssr