imgproxy-url-builder 1.2.1

imgproxy-url-builder

A helper library for building imgproxy URLs.

Installation

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

Usage

You can simply import the param builder and chain your transformations.

For a list of available transformations visit the API documentation page.

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

Modifiers

adjust
autoRotate
background
backgroundAlpha
blur
blurDetections
brightness
cacheBuster
contrast
crop
disableAnimation
dpr
drawDetections
enforceThumbnail
enlarge
expires
extend
fallbackImageUrl
fileName
format
formatQuality
gradient
gravity
jpegOptions
keepCopyright
maxBytes
minHeight
minWidth
pad
page
pixelate
pngOptions
preset
quality
raw
resize
resizingAlgorithm
returnAttachment
rotate
saturation
sharpen
skipProcessing
stripColorProfile
stripMetadata
style
trim
unsharpen
videoThumbnailSecond
watermark
watermarkShadow
watermarkSize
watermarkText
watermarkUrl
zoom

adjust (imgproxy docs)

Defines the brightness, contrast, and saturation.

Example

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.

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, // 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.

Example

pb().disableAnimation();

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'],
});

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(new Date());

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  // required
    offset: {                // optional
      x: 10;                 // required
      y: 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

pb().fileName('filename.png');

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, // required
  color: 'ababab', // optional
  direction: 'up', // optional
  start: 0.0, // optional
  stop: 0.7, // optional
});

gravity (imgproxy docs)

Sets the gravity.

Example

pb().gravity({
  type: GravityType.NORTH  // required
  offset: {                // optional
    x: 10,                 // required
    y: 20                  // required
  }
});

jpegOptions (imgproxy docs)

Allows redefining JPEG saving options.

Example

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.

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);

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, // 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.

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, // optional
  quantize: false, // optional
  quantization_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, // optional
  width: 100, // optional
  height: 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, // required
  color: 'ffffff', // optional
  equal: {
    // optional
    horizontal: true, // optional
    vertical: true, // optional
  },
});

unsharpen (imgproxy docs)

Allows redefining unsharpening options.

Example

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

videoThumbnailSecond (imgproxy docs)

Redefines the second used for the thumbnail.

Example

pb().videoThumbnailSecond(3);

watermark (imgproxy docs)

Places a watermark on the processed image.

Example

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.

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, // required
  height: 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);

imgproxy-url-builder 1.2.1

Install from the command line:

Install via package.json:

About this version

imgproxy-url-builder

Installation

Usage

Modifiers

adjust (imgproxy docs)

Example

autoRotate (imgproxy docs)

Example

background (imgproxy docs)

Example

backgroundAlpha (imgproxy docs)

Example

blur (imgproxy docs)

Example

blurDetections (imgproxy docs)

Example

brightness (imgproxy docs)

Example

cacheBuster (imgproxy docs)

Example

contrast (imgproxy docs)

Example

crop (imgproxy docs)

Example

disableAnimation (imgproxy docs)

Example

dpr (imgproxy docs)

Example

drawDetections (imgproxy docs)

Example

enforceThumbnail (imgproxy docs)

Example

enlarge (imgproxy docs)

Example

expires (imgproxy docs)

Example

extend (imgproxy docs)

Example

fallbackImageUrl (imgproxy docs)

Example

fileName (imgproxy docs)

Example

format (imgproxy docs)

Example

formatQuality (imgproxy docs)

Example

gradient (imgproxy docs)

Example

gravity (imgproxy docs)

Example

jpegOptions (imgproxy docs)

Example

keepCopyright (imgproxy docs)

Example

maxBytes (imgproxy docs)

Example

minHeight (imgproxy docs)

Example

minWidth (imgproxy docs)

Example

pad (imgproxy docs)

Example

page (imgproxy docs)

Example

pixelate (imgproxy docs)

Example

pngOptions (imgproxy docs)

Example

preset (imgproxy docs)

Example

quality (imgproxy docs)

Example

raw (imgproxy docs)

Example

resize (imgproxy docs)

Example