Introduction
Optimize Images in your Angular Application using the built-in NgOptimizedImage directive powered by incredible sharp backend.
What is ng-image-optimizer?
The ng-image-optimizer library extends Angular's native image capabilities by providing a high-performance Express middleware that intercepts image requests, processes them using the sharp library, and caches the results on disk.
Key Features
- 🚀 Performance: Automatic resizing, format conversion (WebP/AVIF), and quality adjustment.
- ⚡ Seamless Integration: Works directly with Angular's built-in
NgOptimizedImagedirective. - 💾 Advanced Caching: Persistent file-based caching with LRU (Least Recently Used) logic to minimize server load.
- 🛡️ Secure by Default: Built-in Content Security Policy (CSP) headers and SVG protection.
- 🛠️ Automated Setup: Includes an
ng addschematic for zero-config integration. - 🌍 Remote Image Support: Securely fetch and optimize images from external domains via allowlists.
Why do I need it?
While Angular provides the NgOptimizedImage directive to ensure images are loaded correctly with performance best-practices (lazy-loading, fetchpriority), it does not actually resize or compress image files on your server. You still need a backend image loader to handle the processing. That's where ng-image-optimizer steps in, bringing Next.js-level image optimization natively to Angular projects.
Example (AOT / Build Mode)
Same source file (/cairo.jpg), two delivery paths — a standard <img> pulls the full JPEG from disk, while NgOptimizedImage routes through the optimizer.
~80% smaller (2.2 MB saved) with ng-image-optimizer
<img>2.5 MB
NgOptimizedImage134 KB
File sizes
| Variant | Format | Dimensions | Size |
|---|---|---|---|
| Source on disk | JPEG | 5379 × 3585 | 2.5 MB |
| NgOptimizedImage | WebP | 640 × 400 | 43 KB |
| NgOptimizedImage | WebP | 828 × 600 | 70 KB |
| NgOptimizedImage | WebP | 1080 × 600 | 134 KB |
| NgOptimizedImage | WebP | 1920 × 1200 | 387 KB |
| Savings | — | _ | ~80% |
Dual-engine architecture
Version 1.0 introduces two isolated, fully tree-shakable operational modes. Pick one per application — they are not meant to run together.
SSR / Dynamic Mode
Sharp-powered Express middleware optimizes images on demand at request time — resize, reformat (WebP/AVIF), and cache to disk.
Best for SSR apps, dynamic platforms, and user-uploaded media. Set up SSR mode →
AOT / Build Mode
A post-build CLI pre-generates every responsive variant at compile time. The client loader points directly at static files — zero runtime image processing.
Best for SSG, Jamstack, GitHub Pages, Vercel, and Netlify. Set up AOT mode →
Why not just NgOptimizedImage alone?
Angular's directive enforces loading best practices — lazy loading, priority hints, and correct srcset syntax — but it does not compress or resize files on disk or at the CDN edge. You still need an engine behind the loader. ng-image-optimizer fills that gap with a Next.js-style pipeline, purpose-built for Angular SSR and static deployments.