@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 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

``bash
npm install @mts-pjsc/image-optimize
`

Requirements

- React 16.0.0 or higher

Basic Usage

Replace standard elements with the Image component:

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

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

API Reference

$3

The Image component accepts all standard 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 |

$3

Configure global behavior through static properties:

`tsx
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

$3

`tsx
src="/images/photo.jpg"
alt="High quality photo"
quality={85}
/>
`

$3

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

$3

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

$3

`tsx
// 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:

`tsx
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