@mts-pjsc/image-optimize 1.3.10 → 1.3.12

package/README.md

@@ -1,41 +1,167 @@
-# React component for using optimized images in the browser.
+# @mts-pjsc/image-optimize
 
-Works in conjunction with the [Image Optimizer](https://github.com/MobileTeleSystems/image-optimize).
+[![npm version](https://img.shields.io/npm/v/@mts-pjsc/image-optimize.svg?style=flat)](https://www.npmjs.com/package/@mts-pjsc/image-optimize)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
 
-Optimizing images helps reduce image weight and increases website loading speed, which is very important for both users and search engines. For these purposes, we have created a microservice that perfectly copes with this task.
+A React component for automatic image optimization. Works in conjunction with the [Image Optimizer](https://github.com/MobileTeleSystems/image-optimize) microservice.
 
-Features:
-- Resize images for the user's screen size,
-- Image compressions to reduce traffic,
-- Converting images to modern formats such as webp and avif,
-- Works with dynamic content, compression occurs on the fly,
-- High compression speed, an average picture is processed in just 200 ms,
-- Includes exporter of metrics for Prometheus,
-- Supports basic authorization for multiple domains and endpoints,
-- Supports security restrictions for allowed addresses.
+## Overview
 
-### Before use
-[The optimization microservice](https://github.com/MobileTeleSystems/image-optimize) must be deployed on the server along the path `/optimizer`. React component will use it.
+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.
 
-### Installation
+## Features
 
-Run script:
+- **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](https://github.com/MobileTeleSystems/image-optimize) microservice must be deployed and accessible at the `/optimizer` path on your server.
+
+## Installation
 
 ```bash
-npm i @mts-pjsc/image-optimize
+npm install @mts-pjsc/image-optimize
+```
+
+## Requirements
+
+- React 16.0.0 or higher
+
+## Basic Usage
+
+Replace standard `<img>` elements with the `Image` component:
+
+```tsx
+import { Image } from "@mts-pjsc/image-optimize";
+
+function App() {
+    return (
+        <Image
+            src="/images/hero-banner.png"
+            alt="Hero banner"
+        />
+    );
+}
 ```
 
-### Using
+## API Reference
+
+### Image Component
+
+The `Image` component accepts all standard `<img>` attributes plus the following:
 
-Just replace the \<img\> element with the Image component from the package. The component is fully compatible with the \<img\> element. Next, the component will do all the magic on its own.
+| 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 |
 
-Sample:
+### Static Configuration
 
-```typescript
-import {Image} from "@mts-pjsc/image-optimize";
+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
+
+### With Quality Control
+
+```tsx
 <Image
-    alt="Sample of work Image Optimizer"
-    src="/static/landing/images-getmeback/phone-fon.png"
+    src="/images/photo.jpg"
+    alt="High quality photo"
+    quality={85}
 />
 ```
+
+### With Size Offset
+
+```tsx
+// Request a larger size than calculated (useful for hero images)
+<Image
+    src="/images/banner.png"
+    alt="Banner"
+    offset={1}
+/>
+```
+
+### With Ref Callback
+
+```tsx
+<Image
+    src="/images/chart.png"
+    alt="Chart"
+    setRef={(elem) => {
+        if (elem) {
+            elem.decode().then(() => console.log("Image decoded"));
+        }
+    }}
+/>
+```
+
+### Development Configuration
+
+```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](./CONTRIBUTING.md) for development guidelines.
+
+## Related Projects
+
+- [Image Optimizer](https://github.com/MobileTeleSystems/image-optimize) — Backend microservice for image optimization

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@mts-pjsc/image-optimize",
-  "version": "1.3.10",
+  "version": "1.3.12",
   "description": "React component for image optimizer",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "esnext": "dist/index.js",
   "type": "module",
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "eslint": "eslint --fix -c eslint.config.js --ext .tsx,.ts,.jsx,.js ./src/",
     "test": "echo \"Error: no test specified. For test need deployed microservice part\" && exit 1",
@@ -40,7 +43,7 @@
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@labeg/code-style": "^6.10.3",
-    "@types/node": "^24.10.1",
+    "@types/node": "^25.0.8",
     "@types/react": "^19.2.6",
     "@favware/cliff-jumper": "^6.0.0",
     "husky": "^9.1.7",