@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
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
- The component mounts and measures the container width
- Based on container size and device pixel ratio, it selects an optimal size from the control points
- Browser capabilities are detected (AVIF > WebP > original format)
- A request URL is constructed:
/optimizer/optimize?src=...&size=...&format=...
- The optimized image is loaded and displayed
- 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