express-image-opt

On-the-fly image optimization middleware for Express.js applications. Resize and compress images dynamically using URL query parameters.

Features

• 🚀 On-the-fly optimization - No pre-processing required
• 🖼️ Multiple formats - Support for JPEG, PNG, WebP, and AVIF
• 📐 Dynamic resizing - Resize images via URL query parameters
• 🗜️ Smart compression - Optimize file size while maintaining quality
• ⚡ Stream-based - Efficient memory usage with Node.js streams
• 🎯 Flexible fit modes - Control how images are resized

Installation

npm install express-image-opt

Requirements

• Node.js 14 or higher
• Express.js

Usage

Basic Setup

import express from 'express';
import { imageOptimizer } from 'express-image-opt';

const app = express();

// IMPORTANT: Register imageOptimizer BEFORE express.static
// This ensures image optimization happens before serving static files
app.use(imageOptimizer('public'));
app.use(express.static('public'));

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

⚠️ Important: The imageOptimizer middleware must be registered before express.static or any other static file serving middleware. This ensures that image requests are intercepted and optimized before being served as regular static files.

Query Parameters

Optimize images by adding query parameters to image URLs:

http://localhost:3000/images/photo.jpg?w=800&h=600&q=85&fit=cover

Available Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | w | number | original width | Target width in pixels | | h | number | original height | Target height in pixels | | q | number | 100 | Quality (0-100) | | fit | string | cover | Resize fit mode | | enlarge | boolean | false | Allow enlargement beyond original size |

Fit Modes

• cover - Resize to cover both dimensions, cropping if necessary
• contain - Resize to fit within dimensions, maintaining aspect ratio
• fill - Resize to exact dimensions, ignoring aspect ratio
• inside - Resize to fit inside dimensions, maintaining aspect ratio
• outside - Resize to cover dimensions, maintaining aspect ratio

Examples

Resize to specific width

/image.jpg?w=500

Resize with compression

/image.jpg?w=800&h=600&q=80

Resize with specific fit mode

/image.jpg?w=400&h=400&fit=contain

Allow enlargement

/image.jpg?w=2000&enlarge=true

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)
• AVIF (.avif)

How It Works

1. The middleware intercepts requests for image files
2. Checks if the file exists in the specified root directory
3. Reads query parameters to determine optimization settings
4. Uses Sharp to process the image
5. Streams the optimized image directly to the response

Configuration

The imageOptimizer function accepts a single parameter:

imageOptimizer(root: string)

• root - The directory path where images are stored (relative to process.cwd())

Performance Considerations

• Images are processed on-demand for each request
• No caching is implemented by default - consider adding a caching layer for production
• Uses streaming to minimize memory usage
• Original files are never modified

Error Handling

The middleware will call next() in the following cases:

• The requested file is not an image
• The file doesn't exist
• The image format is not supported for compression
• Any other errors during processing

Dependencies

• sharp - High-performance image processing
• mime - MIME type detection

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

If you encounter any issues or have questions, please file an issue on the GitHub repository.

Changelog

1.0.0

• Initial release
• Support for JPEG, PNG, WebP, and AVIF formats
• Dynamic resizing and compression
• Multiple fit modes