@mts-pjsc/image-optimize

A React component for automatic image optimization. Works in conjunction with the Image Optimizer microservice.

Overview

This library provides a drop-in replacement for the standard <img> element that automatically optimizes images based on the user's device, screen size, and browser capabilities. The component communicates with a backend optimization service to deliver the most efficient image format and size.

Features

• Responsive resizing — automatically selects optimal image dimensions based on container size and device pixel ratio
• Modern format support — converts images to WebP or AVIF when supported by the browser
• Quality control — configurable compression quality for fine-tuned optimization
• Lazy evaluation — determines optimal size after component mount for accurate container measurement
• Resize handling — recalculates optimal image size on window resize with debouncing
• Next.js compatible — includes "use client" directive for React Server Components support
• Zero configuration — works out of the box with sensible defaults

Prerequisites

The Image Optimizer microservice must be deployed and accessible at the /optimizer path on your server.

Installation

npm install @mts-pjsc/image-optimize

Requirements

• React 16.0.0 or higher

Basic Usage

Replace standard <img> elements with the Image component:

import { Image } from "@mts-pjsc/image-optimize";

function App() {
    return (
        <Image
            src="/images/hero-banner.png"
            alt="Hero banner"
        />
    );
}

API Reference

Image Component

The Image component accepts all standard <img> attributes plus the following:

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | — | Required. Image source URL | | alt | string | — | Required. Alternative text for accessibility | | offset | number | 0 | Adjust the selected size breakpoint (-1 for smaller, +1 for larger) | | quality | number | — | Compression quality (0-100). Uses server default if not specified | | setRef | (elem: HTMLImageElement \| null) => void | — | Callback to receive the underlying img element reference |

Static Configuration

Configure global behavior through static properties:

import { Image } from "@mts-pjsc/image-optimize";

// Skip optimization and use original URLs (useful for local development)
Image.isUseSourceUrl = process.env.NODE_ENV !== "production";

// Override image origin for CORS or microfrontend scenarios
Image.imgOrigin = "https://cdn.example.com";

// Custom breakpoints for responsive sizing (default: [160, 320, 640, 1280, 1920])
Image.controlPoints = [320, 640, 1024, 1440, 2560];

// Enable diagnostic logging in development
Image.isShowDiagnostic = true;

Examples

With Quality Control

<Image
    src="/images/photo.jpg"
    alt="High quality photo"
    quality={85}
/>

With Size Offset

// Request a larger size than calculated (useful for hero images)
<Image
    src="/images/banner.png"
    alt="Banner"
    offset={1}
/>

With Ref Callback

<Image
    src="/images/chart.png"
    alt="Chart"
    setRef={(elem) => {
        if (elem) {
            elem.decode().then(() => console.log("Image decoded"));
        }
    }}
/>

Development Configuration

// In your app initialization
import { Image } from "@mts-pjsc/image-optimize";

if (process.env.NODE_ENV !== "production") {
    Image.isUseSourceUrl = true;
    Image.isShowDiagnostic = true;
}

How It Works

1. The component mounts and measures the container width
2. Based on container size and device pixel ratio, it selects an optimal size from the control points
3. Browser capabilities are detected (AVIF > WebP > original format)
4. A request URL is constructed: /optimizer/optimize?src=...&size=...&format=...
5. The optimized image is loaded and displayed
6. On window resize, the process repeats with debouncing to prevent excessive requests

Helper Functions

The library also exports utility functions for format detection:

import { checkWebpFeature, checkAvifFeature } from "@mts-pjsc/image-optimize";

const supportsWebP = await checkWebpFeature();
const supportsAvif = await checkAvifFeature();

License

Apache-2.0

Contributing

See CONTRIBUTING.md for development guidelines.

Related Projects

• Image Optimizer — Backend microservice for image optimization