GitHub Workflow Status Coverage Status npm
A TypeScript helper library for building imgproxy URLs.
npm i --save @bitpatty/imgproxy-url-builder
You can import the param builder and chain your transformations. For a list of available transformations check the sections below.
import pb from '@bitpatty/imgproxy-url-builder'; // Just the transformer params // Returns rot:90/bl:10 pb().rotate(90).blur(10).build(); // The transformer params with the target image // Returns /-/rot:90/bl:10/czM6Ly9teWJ1Y2tldC9teWltYWdlLnBuZw pb().rotate(90).blur(10).build({ path: 's3://mybucket/myimage.png', }); // You can disable path encoding by setting 'plain' to true // Returns /-/rot:90/bl:10/plain/s3://mybucket/myimage.png pb().rotate(90).blur(10).build({ plain: true, path: 's3://mybucket/myimage.png', }); // To sign your URL provide the key and salt // The path is required to sign your URL! // Returns /TXf2QXtZkU-ULvrg0pLDqJlWUb7XdHkXD0h6NFWD-mo/rot:90/bl:10/czM6Ly9teWJ1Y2tldC9teWltYWdlLnBuZw pb() .rotate(90) .blur(10) .build({ path: 's3://mybucket/myimage.png', signature: { key: 'a91bdcda48ce22cd7d8d3a0eda93', salt: 'a91bdcda48ce22cd7d8d3a0eda93', size: 32, // Optional, specify the signature size. Defaults to 32 }, }); // To automatically prepend the imgproxy URL // provide it as the 'baseUrl' setting // Returns https://my-imgproxy-instance.example.com/-/rot:90/bl:10/czM6Ly9teWJ1Y2tldC9teWltYWdlLnBuZw pb().rotate(90).blur(10).build({ path: 's3://mybucket/myimage.png', baseUrl: 'https://my-imgproxy-instance.example.com', }); // You can clone the current configuration for templating / reuse const template = pb().rotate(90); const copy = template.clone(); // To remove a modifier, use the `unset` function const t = pb().rotate(90).blur(10); t.unset('rotate'); // ... Or you can replace the previous setting by calling the // modifier again const t = pb().rotate(90).blur(10); // rotate: 90, blur: 10 t.rotate(34); // rotate: 34, blur: 10
Pipelines can be chained using the chain utility function:
import pb, { chain } from '@bitpatty/imgproxy-url-builder'; // Returns bl:10/rot:90/-/bl:10/rot:270 chain([pb().blur(10).rotate(90), pb().blur(10).rotate(270)]); // Returns /8q2Ey2URdWizZb8PgAUKMO6C2tD4aXOa2IbCMV9pTKA/bl:10/-/ar:true/dGVzdC5wbmc chain({ buildOptions: { path: 'test.png', signature: { key: '73757065722d7365637265742d6b6579', // super-secret-key salt: '73757065722d7365637265742d73616c74', // super-secret-salt }, }, builders: [pb().blur(10), pb().autoRotate()], });
Published under the MIT License.
- adjust
- autoRotate
- background
- backgroundAlpha
- blur
- blurDetections
- brightness
- cacheBuster
- contrast
- crop
- disableAnimation
- dpi
- dpr
- drawDetections
- duotone
- enforceThumbnail
- enlarge
- expires
- extend
- extendAspectRatio
- fallbackImageUrl
- fileName
- format
- formatQuality
- gradient
- gravity
- hashsum
- jpegOptions
- keepCopyright
- maxBytes
- minHeight
- minWidth
- monochrome
- pad
- page
- pixelate
- pngOptions
- preset
- quality
- raw
- resize
- resizingAlgorithm
- returnAttachment
- rotate
- saturation
- sharpen
- skipProcessing
- stripColorProfile
- stripMetadata
- style
- trim
- unsharpen
- videoThumbnailKeyframes
- videoThumbnailSecond
- videoThumbnailTile
- watermark
- watermarkShadow
- watermarkSize
- watermarkText
- watermarkUrl
- zoom
adjust (imgproxy docs)
Defines the brightness, contrast, and saturation.
pb().adjust({ brightness: 100, // optional contrast: 0.8, // optional saturation: 0.9 // optional });
autoRotate (imgproxy docs)
Automatically rotates the image based on the EXIF orientation parameter.
pb().autoRotate();
background (imgproxy docs)
Fills the image background with the specified color.
pb().background('ff0000'); pb().background({ r: 255, g: 0, b: 0 });
backgroundAlpha (imgproxy docs)
Adds alpha channel to background.
pb().backgroundAlpha(0.4);
blur (imgproxy docs)
Applies a gaussian blur filter to the image.
pb().blur(10);
blurDetections (imgproxy docs)
Detects objects of the provided classes and blurs them.
pb().blurDetections({ sigma: 10, classNames: ['face'] });
brightness (imgproxy docs)
Adjusts the brightness of an image.
pb().brightness(-100);
cacheBuster (imgproxy docs)
Adds a cache buster to the imgproxy params.
pb().cacheBuster("abcdef123");
contrast (imgproxy docs)
Adjust contrast of the resulting image.
pb().contrast(0.3);
crop (imgproxy docs)
Crops the image.
pb().crop({ width: 100, // optional height: 50, // optional gravity: { // optional type: GravityType.CENTER, // required offset: { // optional x: 20, // required y: 20 // required } } })
disableAnimation (imgproxy docs)
Use a single frame of animated images.
pb().disableAnimation();
dpi (imgproxy docs)
When set, imgproxy will replace the image's DPI metadata with the provided value.
pb().dpi(300);
dpr (imgproxy docs)
Multiplies the dimensions according to the specified factor.
pb().dpr(18);
drawDetections (imgproxy docs)
Detects objects of the provided classes and draws their bounding boxes.
pb().drawDetections({ classNames: ["face"] });
duotone (imgproxy docs)
Converts the image to duotone with specified intensity and colors.
pb().duotone({ intensity: 1.0, // required color1: 'ff0000', // required color2: '00ff00' // required });
enforceThumbnail (imgproxy docs)
If the source image has an embedded thumbnail, imgproxy will use the embedded thumbnail instead of the main image.
pb().enforceThumbnail();
enlarge (imgproxy docs)
Enlarges the image if it is smaller than the given size.
pb().enlarge();
expires (imgproxy docs)
Returns a 404 if the expiration date is reached.
pb().expires(new Date()); pb().expires(1661431326);
extend (imgproxy docs)
Extends the image if it is smaller than the given size.
pb().extend(); pb().extend({ gravity: { type: GravityType.NORTH // required offset: { // optional x: 10; // required y: 20; // required } } });
extendAspectRatio (imgproxy docs)
Extends the image to the requested aspect ratio.
pb().extendAspectRatio(); pb().extendAspectRatio({ gravity: { type: GravityType.NORTH // required offset: { // optional x: 10; // required y: 20; // required } } });
fallbackImageUrl (imgproxy docs)
Sets a custom fallback image by specifying its URL.
pb().fallbackImageUrl('https://example.com');
fileName (imgproxy docs)
Sets the filename for the Content-Disposition header.
// Not encoded pb().fileName('filename.png'); // Encoded pb().fileName('ZmlsZW5hbWUucG5n', true);
format (imgproxy docs)
Specifies the resulting image format.
pb().format('png');
formatQuality (imgproxy docs)
Sets the desired quality for each format.
pb().formatQuality({ jpeg: 100, png: 50, // ... });
gradient (imgproxy docs)
Places a gradient on the processed image.
pb().gradient({ opacity: 1, // required color: 'ababab', // optional direction: 'up', // optional start: 0.0, // optional stop: 0.7 // optional });
gravity (imgproxy docs)
Sets the gravity.
pb().gravity({ type: GravityType.NORTH // required offset: { // optional x: 10, // required y: 20 // required } });
hashsum (imgproxy docs)
When hashsum_type is not none, imgproxy will calculate the hashsum of the source image and compare it with the provided hashsum.
pb().hashsum({ hashsum: 'ABCDEF', // required type: HashsumType.NONE // optional });
jpegOptions (imgproxy docs)
Allows redefining JPEG saving options.
pb().jpegOptions({ progressive: boolean, // optional noSubsample: boolean, // optional trellisQuant: boolean, // optional overshootDeringing: boolean, // optional optimizeScans: boolean, // optional quantizationTable: 7 // optional });
keepCopyright (imgproxy docs)
Preserve the copyright info while stripping metadata.
pb().keepCopyright();
maxBytes (imgproxy docs)
Limits the file size to the specified number of bytes.
pb().maxBytes(10);
minHeight (imgproxy docs)
Defines the minimum height of the resulting image.
pb().minHeight(100);
minWidth (imgproxy docs)
Defines the minimum width of the resulting image.
pb().minWidth(100);
monochrome (imgproxy docs)
Converts the image to monochrome.
pb().monochrome({ intensity: 0.3, // required color: 'ff0000' // optional });
pad (imgproxy docs)
Applies the specified padding to the image.
pb().pad({ top: 100, // optional (Note: sets all other sides if not set explicitly) right: 100, // optional bottom: 10, // optional left: 10 // optional });
page (imgproxy docs)
When source image supports pagination (PDF, TIFF) or animation (GIF, WebP), this option allows specifying the page to use.
pb().page(10);
pixelate (imgproxy docs)
Apply the pixelate filter to the resulting image.
pb().pixelate(5);
pngOptions (imgproxy docs)
Allows redefining PNG saving options.
pb().pngOptions({ interlaced: true, // optional quantize: false, // optional quantization_colors: 10 // optional });
preset (imgproxy docs)
Sets one or many presets to be used by the imgproxy.
pb().preset('mypreset'); pb().preset(['preset1', 'preset2']);
quality (imgproxy docs)
Redefines the quality of the resulting image.
pb().quality(80);
raw (imgproxy docs)
Returns a raw unprocessed and unchecked source image
pb().raw();
resize (imgproxy docs)
Resizes the image.
pb().resize({ type: ResizeType.AUTO, // optional width: 100, // optional height: 50 // optional });
resizingAlgorithm (imgproxy docs)
Defines the algorithm that imgproxy will use for resizing.
pb().resizingAlgorithm(ResizingAlgorithm.NEAREST));
returnAttachment (imgproxy docs)
Returns attachment in the Content-Disposition header.
pb().returnAttachment();
rotate (imgproxy docs)
Rotates the image by the specified angle.
pb().rotate(90);
saturation (imgproxy docs)
Adjust saturation of the resulting image.
pb().saturation(0.3);
sharpen (imgproxy docs)
Applies a sharpen filter to the image.
pb().sharpen(3);
skipProcessing (imgproxy docs)
Skip the processing of the listed formats.
pb().skipProcessing(['png', 'svg']);
stripColorProfile (imgproxy docs)
Strips the color profile from the image.
pb().stripColorProfile();
stripMetadata (imgproxy docs)
Strips the metadata from the image.
pb().stripMetadata();
style (imgproxy docs)
Prepend a <style> node with the provided CSS styles to the <svg> node of a source SVG image.
pb().style('fill:red;width:30px;'); pb().style({ fill: 'red'; width: '30px' });
trim (imgproxy docs)
Trims the image background.
pb().trim({ threshold: 10, // required color: 'ffffff', // optional equal: { // optional horizontal: true, // optional vertical: true // optional } });
unsharpen (imgproxy docs)
Allows redefining unsharpening options.
pb().unsharpen({ mode: UnsharpeningMode.AUTO, // optional weight: 11, // optional dividor: 24 // optional });
videoThumbnailKeyframes (imgproxy docs)
Specifies whether the latest keyframe before the video thumbnail second should be used for thumbnail generation
pb().videoThumbnailKeyframes(true);
videoThumbnailSecond (imgproxy docs)
Redefines the second used for the thumbnail.
pb().videoThumbnailSecond(3);
videoThumbnailTile (imgproxy docs)
Generates a tiled sprite using the source video frames
pb().videoThumbnailTile({ step: 1, // required columns: 1, // required rows: 1, // required tileWidth: 50, // required tileHeight: 50, // required extendTile: true, // optional trim: true, // optional fill: true, // optional focusX: 10.3, // optional focusY: 10.3, // optional });
watermark (imgproxy docs)
Places a watermark on the processed image.
pb().watermark({ opacity: 0.8, // required position: WatermarkPosition.REPLICATE // optional scale: 2 // optional }); pb().watermark({ opacity: 1.0, scale: 1, position: WatermarkPosition.WEST // optional offset: { // optional x: 10, // optional y: 10 // optional } })
watermarkShadow (imgproxy docs)
Adds a shadow to the watermark.
pb().watermarkShadow(10);
watermarkSize (imgproxy docs)
Defines the desired width and height of the watermark. imgproxy always uses fit resizing type when resizing watermarks and enlarges them when needed.
pb().watermarkSize({ width: 30, // required height: 30 // required });
watermarkText (imgproxy docs)
Generate an image from the provided text and use it as a watermark.
pb().watermarkText("my watermark");
watermarkUrl (imgproxy docs)
Use the image from the specified URL as a watermark.
pb().watermarkUrl('https://example.com');
zoom (imgproxy docs)
Multiply the image dimensions according to the specified factors.
pb().zoom(3);