Skip to content

Commit a2a5def

Browse files
LabEGLabEG
committed
chore: remove .npmignore, add Code of Conduct, and update README with detailed usage and features
1 parent 1ab3760 commit a2a5def

4 files changed

Lines changed: 285 additions & 29 deletions

File tree

‎.npmignore‎

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎CODE_OF_CONDUCT.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the overall
26+
community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or advances of
31+
any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email address,
35+
without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
the [GitHub Issues](https://github.com/MobileTeleSystems/image-optimize-react/issues).
64+
All complaints will be reviewed and investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series of
86+
actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or permanent
93+
ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within the
113+
community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.1, available at
119+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
120+
121+
Community Impact Guidelines were inspired by
122+
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
123+
124+
For answers to common questions about this code of conduct, see the FAQ at
125+
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
126+
[https://www.contributor-covenant.org/translations][translations].
127+
128+
[homepage]: https://www.contributor-covenant.org
129+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
130+
[Mozilla CoC]: https://github.com/mozilla/diversity
131+
[FAQ]: https://www.contributor-covenant.org/faq
132+
[translations]: https://www.contributor-covenant.org/translations

‎README.md‎

Lines changed: 150 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,167 @@
1-
# React component for using optimized images in the browser.
1+
# @mts-pjsc/image-optimize
22

3-
Works in conjunction with the [Image Optimizer](https://github.com/MobileTeleSystems/image-optimize).
3+
[![npm version](https://img.shields.io/npm/v/@mts-pjsc/image-optimize.svg?style=flat)](https://www.npmjs.com/package/@mts-pjsc/image-optimize)
4+
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
5+
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
46

5-
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.
7+
A React component for automatic image optimization. Works in conjunction with the [Image Optimizer](https://github.com/MobileTeleSystems/image-optimize) microservice.
68

7-
Features:
8-
- Resize images for the user's screen size,
9-
- Image compressions to reduce traffic,
10-
- Converting images to modern formats such as webp and avif,
11-
- Works with dynamic content, compression occurs on the fly,
12-
- High compression speed, an average picture is processed in just 200 ms,
13-
- Includes exporter of metrics for Prometheus,
14-
- Supports basic authorization for multiple domains and endpoints,
15-
- Supports security restrictions for allowed addresses.
9+
## Overview
1610

17-
### Before use
18-
[The optimization microservice](https://github.com/MobileTeleSystems/image-optimize) must be deployed on the server along the path `/optimizer`. React component will use it.
11+
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.
1912

20-
### Installation
13+
## Features
2114

22-
Run script:
15+
- **Responsive resizing** — automatically selects optimal image dimensions based on container size and device pixel ratio
16+
- **Modern format support** — converts images to WebP or AVIF when supported by the browser
17+
- **Quality control** — configurable compression quality for fine-tuned optimization
18+
- **Lazy evaluation** — determines optimal size after component mount for accurate container measurement
19+
- **Resize handling** — recalculates optimal image size on window resize with debouncing
20+
- **Next.js compatible** — includes "use client" directive for React Server Components support
21+
- **Zero configuration** — works out of the box with sensible defaults
22+
23+
## Prerequisites
24+
25+
The [Image Optimizer](https://github.com/MobileTeleSystems/image-optimize) microservice must be deployed and accessible at the `/optimizer` path on your server.
26+
27+
## Installation
2328

2429
```bash
25-
npm i @mts-pjsc/image-optimize
30+
npm install @mts-pjsc/image-optimize
31+
```
32+
33+
## Requirements
34+
35+
- React 16.0.0 or higher
36+
37+
## Basic Usage
38+
39+
Replace standard `<img>` elements with the `Image` component:
40+
41+
```tsx
42+
import { Image } from "@mts-pjsc/image-optimize";
43+
44+
function App() {
45+
return (
46+
<Image
47+
src="/images/hero-banner.png"
48+
alt="Hero banner"
49+
/>
50+
);
51+
}
2652
```
2753

28-
### Using
54+
## API Reference
55+
56+
### Image Component
57+
58+
The `Image` component accepts all standard `<img>` attributes plus the following:
2959

30-
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.
60+
| Prop | Type | Default | Description |
61+
|------|------|---------|-------------|
62+
| `src` | `string` | — | Required. Image source URL |
63+
| `alt` | `string` | — | Required. Alternative text for accessibility |
64+
| `offset` | `number` | `0` | Adjust the selected size breakpoint (-1 for smaller, +1 for larger) |
65+
| `quality` | `number` | — | Compression quality (0-100). Uses server default if not specified |
66+
| `setRef` | `(elem: HTMLImageElement \| null) => void` | — | Callback to receive the underlying img element reference |
3167

32-
Sample:
68+
### Static Configuration
3369

34-
```typescript
35-
import {Image} from "@mts-pjsc/image-optimize";
70+
Configure global behavior through static properties:
3671

72+
```tsx
73+
import { Image } from "@mts-pjsc/image-optimize";
74+
75+
// Skip optimization and use original URLs (useful for local development)
76+
Image.isUseSourceUrl = process.env.NODE_ENV !== "production";
77+
78+
// Override image origin for CORS or microfrontend scenarios
79+
Image.imgOrigin = "https://cdn.example.com";
80+
81+
// Custom breakpoints for responsive sizing (default: [160, 320, 640, 1280, 1920])
82+
Image.controlPoints = [320, 640, 1024, 1440, 2560];
83+
84+
// Enable diagnostic logging in development
85+
Image.isShowDiagnostic = true;
86+
```
87+
88+
## Examples
89+
90+
### With Quality Control
91+
92+
```tsx
3793
<Image
38-
alt="Sample of work Image Optimizer"
39-
src="/static/landing/images-getmeback/phone-fon.png"
94+
src="/images/photo.jpg"
95+
alt="High quality photo"
96+
quality={85}
4097
/>
4198
```
99+
100+
### With Size Offset
101+
102+
```tsx
103+
// Request a larger size than calculated (useful for hero images)
104+
<Image
105+
src="/images/banner.png"
106+
alt="Banner"
107+
offset={1}
108+
/>
109+
```
110+
111+
### With Ref Callback
112+
113+
```tsx
114+
<Image
115+
src="/images/chart.png"
116+
alt="Chart"
117+
setRef={(elem) => {
118+
if (elem) {
119+
elem.decode().then(() => console.log("Image decoded"));
120+
}
121+
}}
122+
/>
123+
```
124+
125+
### Development Configuration
126+
127+
```tsx
128+
// In your app initialization
129+
import { Image } from "@mts-pjsc/image-optimize";
130+
131+
if (process.env.NODE_ENV !== "production") {
132+
Image.isUseSourceUrl = true;
133+
Image.isShowDiagnostic = true;
134+
}
135+
```
136+
137+
## How It Works
138+
139+
1. The component mounts and measures the container width
140+
2. Based on container size and device pixel ratio, it selects an optimal size from the control points
141+
3. Browser capabilities are detected (AVIF > WebP > original format)
142+
4. A request URL is constructed: `/optimizer/optimize?src=...&size=...&format=...`
143+
5. The optimized image is loaded and displayed
144+
6. On window resize, the process repeats with debouncing to prevent excessive requests
145+
146+
## Helper Functions
147+
148+
The library also exports utility functions for format detection:
149+
150+
```tsx
151+
import { checkWebpFeature, checkAvifFeature } from "@mts-pjsc/image-optimize";
152+
153+
const supportsWebP = await checkWebpFeature();
154+
const supportsAvif = await checkAvifFeature();
155+
```
156+
157+
## License
158+
159+
Apache-2.0
160+
161+
## Contributing
162+
163+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.
164+
165+
## Related Projects
166+
167+
- [Image Optimizer](https://github.com/MobileTeleSystems/image-optimize) — Backend microservice for image optimization

‎package.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@
66
"module": "dist/index.js",
77
"esnext": "dist/index.js",
88
"type": "module",
9+
"files": [
10+
"dist"
11+
],
912
"scripts": {
1013
"eslint": "eslint --fix -c eslint.config.js --ext .tsx,.ts,.jsx,.js ./src/",
1114
"test": "echo \"Error: no test specified. For test need deployed microservice part\" && exit 1",

0 commit comments

Comments
 (0)