NgImageOptimizer is a high-performance image optimization library for Angular SSR applications. It bridges the gap between Angular's NgOptimizedImage and server-side processing using sharp, providing a Next.js-like image optimization experience.

Documentation

• Node.js (v18+)
• Angular CLI
• Angular SSR

The fastest way to get started is using our automated schematic:

ng add ng-image-optimizer

This command will:

1. Install necessary dependencies (sharp).
2. Register the image loader in your app.config.ts.
3. Configure the optimization middleware in your Express server.ts.

If you prefer to configure things manually, follow these steps:

Install the library and its peer dependencies:

npm install ng-image-optimizer sharp

Register the image loader in your app.config.ts:

import { provideImageOptimizerLoader } from 'ng-image-optimizer';

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

Add the middleware to your server.ts before other routes:

import { imageOptimizerHandler } from 'ng-image-optimizer/server';

// ... early in your express app setup
const browserDistFolder = resolve(serverDistFolder, '../browser');

server.get('/_ng/image', imageOptimizerHandler(browserDistFolder));

• 🚀 Performance: Automatic resizing, format conversion (WebP/AVIF), and quality adjustment.
• ⚡ Seamless Integration: Works directly with Angular's built-in NgOptimizedImage directive.
• 💾 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 add schematic for zero-config integration.
• 🌍 Remote Image Support: Securely fetch and optimize images from external domains via allowlists.

NgImageOptimizer consists of two main parts:

A custom IMAGE_LOADER that transforms Angular's image requests into optimization queries (e.g., /_ng/image?url=...&w=1080&q=75).

An Express middleware that intercept requests, fetches the source image (local or remote), optimizes it using sharp, and caches the result for future hits.

sequenceDiagram
    participant Browser
    participant Express as Server (Express)
    participant Sharp as Optimizer (Sharp)
    participant Disk as Cache (File System)

    Browser->>Express: GET /_ng/image?url=me.jpg&w=640
    Express->>Disk: Check Cache (Hash)
    alt Cache Hit
        Disk-->>Express: Return Cached Buffer
        Express-->>Browser: 200 OK (X-Cache: HIT)
    else Cache Miss
        Express->>Express: Fetch Original Image
        Express->>Sharp: Resize & Compress
        Sharp-->>Express: Optimized Buffer
        Express->>Disk: Save to Cache
        Express-->>Browser: 200 OK (X-Cache: MISS)
    end

Use standard Angular NgOptimizedImage in your templates. The library will automatically handle the resolution and optimization.

<img ngSrc="/photo.jpg" width="800" height="600" priority />

When registering provideImageOptimizerLoader, you can pass the following options:

When initializing imageOptimizerHandler, you can pass an optional configuration object:

ng-image-optimizer is an open source package released under the MIT license. See the LICENSE file for more information.