Created as part of inspishop e-commerce platform by inspirum team.
On-demand image resizing, format converting and size optimization with the best CLI tools. Prepared to be used as Docker image with cloud storage as Amazon S3.
- image resizing, format converting and optimization
- support for jpeg, png, webp, bmp, gif, tiff, svg image formats
- file-cache for resized images on local disk (temporary cache) and cloud storage (persistent cache)
Application handle route with dynamic template (parameters divided by dash) and filepath parameters.
GET /image/{template}/{filepath}
Options for resizing are specified as a dash delimited list of parameters, which can be supplied in any order. Duplicate parameters overwrite last values.
| Name | Template | Example | Description |
|---|---|---|---|
| width | w[X] |
w200 |
Resize to 200px width with proportional height |
| height | h[X] |
h100 |
Resize to 100px height with proportional width |
| ratio | [X]x[X] |
1x2 |
Resize to ratio to 1:2 (width : height) |
| crop | crop |
crop |
Image fill whole canvas (no addition background added) |
| upscale | upscale |
upscale |
Image can be larger than original |
There are special template string original. This will return optimized image with original dimensions.
It is helpful to show image with maximal resolution without knowing its dimension.
When there are set both height and width then ratio parameter will be ignored.
If output image has a different ratio than an original, image will be centered on transparent canvas (jpg has white background because it doesn't support transparent color).
Values are for an image with dimension 200x400px (width : height).
| Template string | Output dimension |
|---|---|
original |
200x400 |
h100 |
50x100 |
w100 |
100x200 |
w50-w200 |
100x200 |
w100-h300 |
100x300 |
w200-1x1 |
200x200 |
w200-1x3 |
200x600 |
w100-h300-2x1 |
100x300 |
w1000-1x1 |
1000x1000 |
w1000-1x1-crop |
200x200 |
w1000-1x1-crop-upscale |
1000x1000 |
Examples use jpg format because canvas background is white (for better visibility)
h200 |
w200 |
w188-h233 |
|---|---|---|
| (300x200) | (200x134) | (188x233) |
 |
 |
 |
h200-1x1 |
h200-1x2 |
h200-2x1 |
|---|---|---|
| (200x200) | (100x200) | (400x200) |
 |
 |
 |
cropparameter will crop image to fill whole canvas
h200-1x1-crop |
h200-1x2-crop |
h200-2x1-crop |
|---|---|---|
| (200x200) | (100x200) | (400x200) |
 |
 |
 |
By default, image can't up-size (be larger than original)
original |
w250-h300 |
w250-h300-upscale |
w250-h300-crop |
w250-h300-crop-upscale |
|---|---|---|---|---|
| (200x200) | (250x300) | (250x300) | (167x200) | (250x300) |
 |
 |
 |
 |
 |
original |
w500-h300-crop |
w500-h300-crop |
w500-h300-crop-upscale |
|---|---|---|---|
| (200x200) | (500x300) | (200x120) | (500x300) |
|
 |
 |
 |
Image can be encoded to any supported format simple by changing file extension in URL.
Original image extension is specified in original query parameter.
This is typically used to encode image as web-friendly webp format
http://localhost:3000/image/custom-w400-1x1-upscale/data/products/0/1/background.webp?original=png
The package will use these optimizers if they are present on your system:
By setting environment variable you can change default path to binary file or default arguments.
| Environment variable | Default value |
|---|---|
CMD_OPTIMIZER_PNG |
pngquant --force --ext .png --skip-if-larger --quality 0-75 --speed 4 --strip -- |
CMD_OPTIMIZER_JPG |
jpegoptim --force --strip-all --max 75 --quiet --all-progressive |
CMD_OPTIMIZER_GIF |
gifsicle --batch --optimize=3 |
CMD_OPTIMIZER_SVG |
svgcleaner |
CMD_OPTIMIZER_WEBP |
cwebp -m 6 -pass 10 -mt -q 75 -quiet |
| 64 kB | 28 kB (43 %) | 22 kB (34 %) |
|---|---|---|
 |
 |
 |
| 421 kB | 91 kB (21 %) | 23 kB (5 %) |
|---|---|---|
 |
 |
 |
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.