imgproxy-url-builder

A TypeScript helper library for building imgproxy URLs.

Installation

npm i --save @bitpatty/imgproxy-url-builder

Usage

You can import the param builder and chain your transformations. For a list of available transformations check the sections below.

importpbfrom'@bitpatty/imgproxy-url-builder';// Just the transformer params// Returns rot:90/bl:10pb().rotate(90).blur(10).build();// The transformer params with the target image// Returns /-/rot:90/bl:10/czM6Ly9teWJ1Y2tldC9teWltYWdlLnBuZwpb().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.pngpb().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/czM6Ly9teWJ1Y2tldC9teWltYWdlLnBuZwpb().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/czM6Ly9teWJ1Y2tldC9teWltYWdlLnBuZwpb().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 / reuseconsttemplate=pb().rotate(90);constcopy=template.clone();// To remove a modifier, use the `unset` functionconstt=pb().rotate(90).blur(10);t.unset('rotate');// ... Or you can replace the previous setting by calling the// modifier againconstt=pb().rotate(90).blur(10);// rotate: 90, blur: 10t.rotate(34);// rotate: 34, blur: 10

Chaining Pipelines

Pipelines can be chained using the chain utility function:

importpb,{chain}from'@bitpatty/imgproxy-url-builder';// Returns bl:10/rot:90/-/bl:10/rot:270chain([pb().blur(10).rotate(90),pb().blur(10).rotate(270)]);// Returns /8q2Ey2URdWizZb8PgAUKMO6C2tD4aXOa2IbCMV9pTKA/bl:10/-/ar:true/dGVzdC5wbmcchain({buildOptions: {path: 'test.png',signature: {key: '73757065722d7365637265742d6b6579',// super-secret-keysalt: '73757065722d7365637265742d73616c74',// super-secret-salt},},builders: [pb().blur(10),pb().autoRotate()],});

License

Published under the MIT License.

Modifiers

• 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.

Example

pb().adjust({brightness: 100,// optionalcontrast: 0.8,// optionalsaturation: 0.9// optional});

autoRotate (imgproxy docs)

Automatically rotates the image based on the EXIF orientation parameter.

Example

pb().autoRotate();

background (imgproxy docs)

Fills the image background with the specified color.

Example

pb().background('ff0000');pb().background({r: 255,g: 0,b: 0});

backgroundAlpha (imgproxy docs)

Adds alpha channel to background.

Example

pb().backgroundAlpha(0.4);

blur (imgproxy docs)

Applies a gaussian blur filter to the image.

Example

pb().blur(10);

blurDetections (imgproxy docs)

Detects objects of the provided classes and blurs them.

Example

pb().blurDetections({sigma: 10,classNames: ['face']});

brightness (imgproxy docs)

Adjusts the brightness of an image.

Example

pb().brightness(-100);

cacheBuster (imgproxy docs)

Adds a cache buster to the imgproxy params.

Example

pb().cacheBuster("abcdef123");

contrast (imgproxy docs)

Adjust contrast of the resulting image.

Example

pb().contrast(0.3);

crop (imgproxy docs)

Crops the image.

Example

pb().crop({width: 100,// optionalheight: 50,// optionalgravity: {// optionaltype: GravityType.CENTER,// requiredoffset: {// optionalx: 20,// requiredy: 20// required}}})

disableAnimation (imgproxy docs)

Use a single frame of animated images.

Example

pb().disableAnimation();

dpi (imgproxy docs)

When set, imgproxy will replace the image's DPI metadata with the provided value.

Example

pb().dpi(300);

dpr (imgproxy docs)

Multiplies the dimensions according to the specified factor.

Example

pb().dpr(18);

drawDetections (imgproxy docs)

Detects objects of the provided classes and draws their bounding boxes.

Example

pb().drawDetections({classNames: ["face"]});

duotone (imgproxy docs)

Converts the image to duotone with specified intensity and colors.

Example

pb().duotone({intensity: 1.0,// requiredcolor1: 'ff0000',// requiredcolor2: '00ff00'// required});

enforceThumbnail (imgproxy docs)

If the source image has an embedded thumbnail, imgproxy will use the embedded thumbnail instead of the main image.

Example

pb().enforceThumbnail();

enlarge (imgproxy docs)

Enlarges the image if it is smaller than the given size.

Example

pb().enlarge();

expires (imgproxy docs)

Returns a 404 if the expiration date is reached.

Example

pb().expires(newDate());pb().expires(1661431326);

extend (imgproxy docs)

Extends the image if it is smaller than the given size.

Example

pb().extend();pb().extend({gravity: {type: GravityType.NORTH// requiredoffset: {// optionalx: 10;// requiredy: 20;// required}}});

extendAspectRatio (imgproxy docs)

Extends the image to the requested aspect ratio.

Example

pb().extendAspectRatio();pb().extendAspectRatio({gravity: {type: GravityType.NORTH// requiredoffset: {// optionalx: 10;// requiredy: 20;// required}}});

fallbackImageUrl (imgproxy docs)

Sets a custom fallback image by specifying its URL.

Example

pb().fallbackImageUrl('https://example.com');

fileName (imgproxy docs)

Sets the filename for the Content-Disposition header.

Example

// Not encodedpb().fileName('filename.png');// Encodedpb().fileName('ZmlsZW5hbWUucG5n',true);

format (imgproxy docs)

Specifies the resulting image format.

Example

pb().format('png');

formatQuality (imgproxy docs)

Sets the desired quality for each format.

Example

pb().formatQuality({jpeg: 100,png: 50,// ...});

gradient (imgproxy docs)

Places a gradient on the processed image.

Example

pb().gradient({opacity: 1,// requiredcolor: 'ababab',// optionaldirection: 'up',// optionalstart: 0.0,// optionalstop: 0.7// optional});

gravity (imgproxy docs)

Sets the gravity.

Example

pb().gravity({type: GravityType.NORTH// requiredoffset: {// optionalx: 10,// requiredy: 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.

Example

pb().hashsum({hashsum: 'ABCDEF',// requiredtype: HashsumType.NONE// optional});

jpegOptions (imgproxy docs)

Allows redefining JPEG saving options.

Example

pb().jpegOptions({progressive: boolean,// optionalnoSubsample: boolean,// optionaltrellisQuant: boolean,// optionalovershootDeringing: boolean,// optionaloptimizeScans: boolean,// optionalquantizationTable: 7// optional});

keepCopyright (imgproxy docs)

Preserve the copyright info while stripping metadata.

Example

pb().keepCopyright();

maxBytes (imgproxy docs)

Limits the file size to the specified number of bytes.

Example

pb().maxBytes(10);

minHeight (imgproxy docs)

Defines the minimum height of the resulting image.

Example

pb().minHeight(100);

minWidth (imgproxy docs)

Defines the minimum width of the resulting image.

Example

pb().minWidth(100);

monochrome (imgproxy docs)

Converts the image to monochrome.

Example

pb().monochrome({intensity: 0.3,// requiredcolor: 'ff0000'// optional});

pad (imgproxy docs)

Applies the specified padding to the image.

Example

pb().pad({top: 100,// optional (Note: sets all other sides if not set explicitly)right: 100,// optionalbottom: 10,// optionalleft: 10// optional});

page (imgproxy docs)

When source image supports pagination (PDF, TIFF) or animation (GIF, WebP), this option allows specifying the page to use.

Example

pb().page(10);

pixelate (imgproxy docs)

Apply the pixelate filter to the resulting image.

Example

pb().pixelate(5);

pngOptions (imgproxy docs)

Allows redefining PNG saving options.

Example

pb().pngOptions({interlaced: true,// optionalquantize: false,// optionalquantization_colors: 10// optional});

preset (imgproxy docs)

Sets one or many presets to be used by the imgproxy.

Example

pb().preset('mypreset');pb().preset(['preset1','preset2']);

quality (imgproxy docs)

Redefines the quality of the resulting image.

Example

pb().quality(80);

raw (imgproxy docs)

Returns a raw unprocessed and unchecked source image

Example

pb().raw();

resize (imgproxy docs)

Resizes the image.

Example

pb().resize({type: ResizeType.AUTO,// optionalwidth: 100,// optionalheight: 50// optional});

resizingAlgorithm (imgproxy docs)

Defines the algorithm that imgproxy will use for resizing.

Example

pb().resizingAlgorithm(ResizingAlgorithm.NEAREST));

returnAttachment (imgproxy docs)

Returns attachment in the Content-Disposition header.

Example

pb().returnAttachment();

rotate (imgproxy docs)

Rotates the image by the specified angle.

Example

pb().rotate(90);

saturation (imgproxy docs)

Adjust saturation of the resulting image.

Example

pb().saturation(0.3);

sharpen (imgproxy docs)

Applies a sharpen filter to the image.

Example

pb().sharpen(3);

skipProcessing (imgproxy docs)

Skip the processing of the listed formats.

Example

pb().skipProcessing(['png','svg']);

stripColorProfile (imgproxy docs)

Strips the color profile from the image.

Example

pb().stripColorProfile();

stripMetadata (imgproxy docs)

Strips the metadata from the image.

Example

pb().stripMetadata();

style (imgproxy docs)

Prepend a <style> node with the provided CSS styles to the <svg> node of a source SVG image.

Example

pb().style('fill:red;width:30px;');pb().style({fill: 'red';
width: '30px'});

trim (imgproxy docs)

Trims the image background.

Example

pb().trim({threshold: 10,// requiredcolor: 'ffffff',// optionalequal: {// optionalhorizontal: true,// optionalvertical: true// optional}});

unsharpen (imgproxy docs)

Allows redefining unsharpening options.

Example

pb().unsharpen({mode: UnsharpeningMode.AUTO,// optionalweight: 11,// optionaldividor: 24// optional});

videoThumbnailKeyframes (imgproxy docs)

Specifies whether the latest keyframe before the video thumbnail second should be used for thumbnail generation

Example

pb().videoThumbnailKeyframes(true);

videoThumbnailSecond (imgproxy docs)

Redefines the second used for the thumbnail.

Example

pb().videoThumbnailSecond(3);

videoThumbnailTile (imgproxy docs)

Generates a tiled sprite using the source video frames

Example

pb().videoThumbnailTile({step: 1,// requiredcolumns: 1,// requiredrows: 1,// requiredtileWidth: 50,// requiredtileHeight: 50,// requiredextendTile: true,// optionaltrim: true,// optionalfill: true,// optionalfocusX: 10.3,// optionalfocusY: 10.3,// optional});

watermark (imgproxy docs)

Places a watermark on the processed image.

Example

pb().watermark({opacity: 0.8,// requiredposition: WatermarkPosition.REPLICATE// optionalscale: 2// optional});pb().watermark({opacity: 1.0,scale: 1,position: WatermarkPosition.WEST// optionaloffset: {// optionalx: 10,// optionaly: 10// optional}})

watermarkShadow (imgproxy docs)

Adds a shadow to the watermark.

Example

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.

Example

pb().watermarkSize({width: 30,// requiredheight: 30// required});

watermarkText (imgproxy docs)

Generate an image from the provided text and use it as a watermark.

Example

pb().watermarkText("my watermark");

watermarkUrl (imgproxy docs)

Use the image from the specified URL as a watermark.

Example

pb().watermarkUrl('https://example.com');

zoom (imgproxy docs)

Multiply the image dimensions according to the specified factors.

Example

pb().zoom(3);