High-performance microservice for on-the-fly image optimization, resizing, and format conversion
Quick Start • API Reference • Configuration • Deployment • Contributing
Image Optimize is a lightweight, production-ready microservice that optimizes images dynamically. Built with NestJS and powered by Sharp, it delivers exceptional performance for modern web applications.
Optimizing images is critical for web performance — reducing page load times, saving bandwidth, and improving SEO rankings. This microservice handles all optimization on-the-fly, requiring no pre-processing or storage of optimized variants.
| Feature | Description |
|---|---|
| Dynamic Resizing | Resize images to any width, perfect for responsive designs |
| Smart Compression | Reduce file sizes with configurable quality settings (1-100) |
| Modern Formats | Convert to WebP, AVIF, JPEG, or PNG on demand |
| High Performance | Average processing time ~200ms per image |
| Prometheus Metrics | Built-in /metrics endpoint for monitoring |
| Security Controls | Allowlist for sources, size restrictions, Basic Auth support |
| Docker Ready | Production-optimized container image |
# Pull and run the latest version
docker run -d --name image-optimize -p 3000:3000 mtsrus/image-optimizeOpen in your browser or use curl:
curl "http://localhost:3000/optimize?src=https://example.com/image.png&size=800&format=webp"http://localhost:3000/optimize?src=https://example.com/photo.jpg&size=1200&format=avif&quality=85
Optimizes and returns an image based on the provided parameters.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
src |
string | ✅ | — | URL-encoded source image URL |
size |
integer | ✅ | — | Target width in pixels |
format |
string | ✅ | — | Output format: jpeg, png, webp, avif |
quality |
integer | ❌ | format default | Compression quality (1-100) |
- Success (200): Returns the optimized image with appropriate
Content-Typeheader - Error (400): Returns JSON with error details
# Convert to WebP with 80% quality, resized to 1920px width
curl -o optimized.webp \
"http://localhost:3000/optimize?src=https%3A%2F%2Fexample.com%2Fimage.png&size=1920&format=webp&quality=80"Returns Prometheus-compatible metrics for monitoring.
curl http://localhost:3000/metricsConfigure the service using environment variables:
| Variable | Default | Description |
|---|---|---|
PORT |
3000 |
HTTP server port |
SHARP_CONCURRENCY |
0 |
libvips thread count (0 = auto-detect CPU cores) |
| Variable | Default | Description |
|---|---|---|
ALLOW_SIZES |
100-1920 |
Allowed output sizes (comma-separated values or ranges) |
ALLOW_SOURCES |
* |
Allowed source URLs (URL-encoded, comma-separated) |
BASIC_AUTHS |
— | Basic auth credentials for sources (see format below) |
# Allow specific sizes only
-e ALLOW_SIZES="320,640,1024,1920"
# Allow a range
-e ALLOW_SIZES="100-2000"
# Mix of specific values and ranges
-e ALLOW_SIZES="320,640,1024-1920"# Allow images only from specific domains
-e ALLOW_SOURCES="https%3A%2F%2Fcdn.example.com%2F,https%3A%2F%2Fimages.example.org%2F"For sources requiring authentication:
# Format: encodeURIComponent(url):encodeURIComponent(login):encodeURIComponent(password)
-e BASIC_AUTHS="https%3A%2F%2Fsecure.example.com%2F:admin:secret123"services:
image-optimize:
image: mtsrus/image-optimize:latest
restart: always
ports:
- "3000:3000"
environment:
- PORT=3000
- ALLOW_SIZES=320,640,1024,1280,1920
- ALLOW_SOURCES=https%3A%2F%2Fcdn.yoursite.com%2F
healthcheck:
test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/metrics"]
interval: 30s
timeout: 10s
retries: 3apiVersion: apps/v1
kind: Deployment
metadata:
name: image-optimize
spec:
replicas: 3
selector:
matchLabels:
app: image-optimize
template:
metadata:
labels:
app: image-optimize
spec:
containers:
- name: image-optimize
image: mtsrus/image-optimize:latest
ports:
- containerPort: 3000
env:
- name: ALLOW_SIZES
value: "320,640,1024,1280,1920"
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "1000m"
livenessProbe:
httpGet:
path: /metrics
port: 3000
initialDelaySeconds: 10
periodSeconds: 30
---
apiVersion: v1
kind: Service
metadata:
name: image-optimize
spec:
selector:
app: image-optimize
ports:
- port: 80
targetPort: 3000- Scaling: Run multiple replicas behind a load balancer
- Caching: Use a CDN or reverse proxy (nginx, Varnish) to cache optimized images
- Memory: Allocate at least 256MB RAM per instance
- Monitoring: Scrape
/metricsendpoint with Prometheus
Use our official React component for seamless integration:
npm install @mts-pjsc/image-optimizeimport { Image } from '@mts-pjsc/image-optimize';
<Image
alt="Optimized image"
src="https://cdn.example.com/photo.jpg"
/>The component automatically handles size detection and format negotiation with the optimization service.
👉 image-optimize-react on GitHub
- Node.js 24+
- npm 10+
# Clone the repository
git clone https://github.com/MobileTeleSystems/image-optimize.git
cd image-optimize
# Install dependencies
npm install
# Run in development mode
npm run start:dev
# Run tests
npm test
# Run e2e tests
npm run test:e2e
# Build for production
npm run buildsrc/
├── controllers/
│ ├── optimize-controller/ # Main optimization endpoint
│ └── metrics/ # Prometheus metrics endpoint
├── services/
│ ├── optimize.service.ts # Image processing logic (Sharp)
│ ├── img-loader.service.ts # Remote image fetching
│ └── allow.service.ts # Security validations
├── enums/
│ └── formats.ts # Supported output formats
└── main.ts # Application entry point
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
Made with ❤️ by MTS