imgproxy-url-builder

A TypeScript helper library for building imgproxy URLs.

Installation

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

Usage

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
Copy

Chaining Pipelines

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

License

Published under the MIT License.

Modifiers

• adjust
• autoRotate
• background
• backgroundAlpha
• blur
• blurDetections
• brightness
• cacheBuster
• contrast
• crop
• disableAnimation
• dpi
• dpr
• drawDetections
• enforceThumbnail
• enlarge
• expires
• extend
• extendAspectRatio
• fallbackImageUrl
• fileName
• format
• formatQuality
• gradient
• gravity
• hashsum
• jpegOptions
• keepCopyright
• maxBytes
• minHeight
• minWidth
• 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, // optional
  contrast: 0.8, // optional
  saturation: 0.9, // optional
});
Copy

autoRotate (imgproxy docs)

Automatically rotates the image based on the EXIF orientation parameter.

Example

pb().autoRotate();
Copy

background (imgproxy docs)

Fills the image background with the specified color.

Example

pb().background('ff0000');

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

backgroundAlpha (imgproxy docs)

Adds alpha channel to background.

Example

pb().backgroundAlpha(0.4);
Copy

blur (imgproxy docs)

Applies a gaussian blur filter to the image.

Example

pb().blur(10);
Copy

blurDetections (imgproxy docs)

Detects objects of the provided classes and blurs them.

Example

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

brightness (imgproxy docs)

Adjusts the brightness of an image.

Example

pb().brightness(-100);
Copy

cacheBuster (imgproxy docs)

Adds a cache buster to the imgproxy params.

Example

pb().cacheBuster('abcdef123');
Copy

contrast (imgproxy docs)

Adjust contrast of the resulting image.

Example

pb().contrast(0.3);
Copy

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

disableAnimation (imgproxy docs)

Use a single frame of animated images.

Example

pb().disableAnimation();
Copy

dpi (imgproxy docs)

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

Example

pb().dpi(300);
Copy

dpr (imgproxy docs)

Multiplies the dimensions according to the specified factor.

Example

pb().dpr(18);
Copy

drawDetections (imgproxy docs)

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

Example

pb().drawDetections({
  classNames: ['face'],
});
Copy

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

enlarge (imgproxy docs)

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

Example

pb().enlarge();
Copy

expires (imgproxy docs)

Returns a 404 if the expiration date is reached.

Example

pb().expires(new Date());

pb().expires(1661431326);
Copy

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

extendAspectRatio (imgproxy docs)

Extends the image to the requested aspect ratio.

Example

pb().extendAspectRatio();

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

fallbackImageUrl (imgproxy docs)

Sets a custom fallback image by specifying its URL.

Example

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

fileName (imgproxy docs)

Sets the filename for the Content-Disposition header.

Example

// Not encoded
pb().fileName('filename.png');

// Encoded
pb().fileName('ZmlsZW5hbWUucG5n', true);
Copy

format (imgproxy docs)

Specifies the resulting image format.

Example

pb().format('png');
Copy

formatQuality (imgproxy docs)

Sets the desired quality for each format.

Example

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

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

gravity (imgproxy docs)

Sets the gravity.

Example

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

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', // required
  type: HashsumType.NONE, // optional
});
Copy

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

keepCopyright (imgproxy docs)

Preserve the copyright info while stripping metadata.

Example

pb().keepCopyright();
Copy

maxBytes (imgproxy docs)

Limits the file size to the specified number of bytes.

Example

pb().maxBytes(10);
Copy

minHeight (imgproxy docs)

Defines the minimum height of the resulting image.

Example

pb().minHeight(100);
Copy

minWidth (imgproxy docs)

Defines the minimum width of the resulting image.

Example

pb().minWidth(100);
Copy

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

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

pixelate (imgproxy docs)

Apply the pixelate filter to the resulting image.

Example

pb().pixelate(5);
Copy

pngOptions (imgproxy docs)

Allows redefining PNG saving options.

Example

pb().pngOptions({
  interlaced: true, // optional
  quantize: false, // optional
  quantization_colors: 10, // optional
});
Copy

preset (imgproxy docs)

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

Example

pb().preset('mypreset');

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

quality (imgproxy docs)

Redefines the quality of the resulting image.

Example

pb().quality(80);
Copy

raw (imgproxy docs)

Returns a raw unprocessed and unchecked source image

Example

pb().raw();
Copy

resize (imgproxy docs)

Resizes the image.

Example

pb().resize({
  type: ResizeType.AUTO, // optional
  width: 100, // optional
  height: 50, // optional
});
Copy

resizingAlgorithm (imgproxy docs)

Defines the algorithm that imgproxy will use for resizing.

Example

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

returnAttachment (imgproxy docs)

Returns attachment in the Content-Disposition header.

Example

pb().returnAttachment();
Copy

rotate (imgproxy docs)

Rotates the image by the specified angle.

Example

pb().rotate(90);
Copy

saturation (imgproxy docs)

Adjust saturation of the resulting image.

Example

pb().saturation(0.3);
Copy

sharpen (imgproxy docs)

Applies a sharpen filter to the image.

Example

pb().sharpen(3);
Copy

skipProcessing (imgproxy docs)

Skip the processing of the listed formats.

Example

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

stripColorProfile (imgproxy docs)

Strips the color profile from the image.

Example

pb().stripColorProfile();
Copy

stripMetadata (imgproxy docs)

Strips the metadata from the image.

Example

pb().stripMetadata();
Copy

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

trim (imgproxy docs)

Trims the image background.

Example

pb().trim({
  threshold: 10, // required
  color: 'ffffff', // optional
  equal: {
    // optional
    horizontal: true, // optional
    vertical: true, // optional
  },
});
Copy

unsharpen (imgproxy docs)

Allows redefining unsharpening options.

Example

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

videoThumbnailKeyframes (imgproxy docs)

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

Example

pb().videoThumbnailKeyframes(true);
Copy

videoThumbnailSecond (imgproxy docs)

Redefines the second used for the thumbnail.

Example

pb().videoThumbnailSecond(3);
Copy

videoThumbnailTile (imgproxy docs)

Generates a tiled sprite using hte source video frames

Example

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

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
  }
})
Copy

watermarkShadow (imgproxy docs)

Adds a shadow to the watermark.

Example

pb().watermarkShadow(10);
Copy

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

watermarkText (imgproxy docs)

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

Example

pb().watermarkText('my watermark');
Copy

watermarkUrl (imgproxy docs)

Use the image from the specified URL as a watermark.

Example

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

zoom (imgproxy docs)

Multiply the image dimensions according to the specified factors.

Example

pb().zoom(3);
Copy