resize.to options parser
Parses a URI fragment and returns a collection of options to pass along to a transformer. This is a building block for creating image transformation services.
Example:
const uriFragment = 'width:100,height:100,output:webp/path/to/image.jpg'
const parser = new Parser(uriFragment)
const optionsCollection = parser.parse()
// optionsCollection == [{ width: 100, height: 100, output: 'webp' }]
// parser.path == 'path/to/image.jpg'
URI Transform Options
Options
-
backgroundalpha
: Default is1
. Possible values are 0-1. This applies when cropping an image which results in the original image not completely covering the new dimensions. Example:backgroundalpha:0.5
-
backgroundcolor
: Default is000
. This is the hex color code value excluding the#
. This is parsed by the color module. This applies when cropping an image which results in the original image not completely covering the new dimensions. Example:backgroundcolor:000
-
blur
: Possible values are 0.3-1000. Example:blur:0.5
-
fit
: Default iscover
. Possible values are:cover
,contain
,fill
,inside
, andoutside
. Check the sharp docs for more information. Example:fit:cover
-
gravity
: Default iscenter
. Possible values are:north
,northeast
,east
,southeast
,south
,southwest
,west
,northwest
,center
,entropy
,attention
. Check the sharp docs for more information. Example:gravity:attention
-
height
: Default is to respect ratio. Acceptable values are a positive integer. Example:height:100
-
left
: This can be a float. Used for custom extraction/crop from the top left corner. Example:width:100,height:100,left:100,top:100
-
mirror
: Possible values are:x
ory
. Will mirror the image across the given axis. Example:mirror:x
-
output
: Default is to use the extension of the image. Possible values are:jpeg
,png
, orwebp
. Example:output:webp
-
quality
: Default is 80. Possible values are 1-100. Applies tojpeg
andwebp
. Example:quality:50
-
rotate
: The value should be an angle and can be a float. The image is auto rotated based on exif data before applying other transforms. Example:rotate:45
-
signature
: Not required but recommended. A sha1 hex digest of the options (excluding signature) and path to the image. This will be verified on the server before processing. -
top
: This can be a float. Used for custom extraction/crop from the top left corner. Example:width:100,height:100,left:100,top:100
-
version
: This is primarily for cache busting. Example:version:101
-
width
: Default is to respect ratio. Acceptable values are a positive integer. Example:width:100
Compound Transforms
It is possible to do to multiple transformations serially by separating groups of options with a semi-colon. For example we could extract part of an image and then resize.
/top:20,left:5,width:250,height:250-width:100,height:100,gravity:entropy-signature:sha1hexdigest/path/to/image.jpg`
Delimiters
There are a few options for what delimiters you can use out of the box. Here is a break down of the URI fragment that is relevant.
- Key-Value pairs (
width:100
): These can be separated by_
,:
, or=
. - Options or groups of key-value pairs (
width:100,height:100
): These can only be separated by,
. - Groups of options (
width:100-blur:0.3
): These can only be separated by-
.
Signing
It is highly recommended that you sign your URIs and keep your token private. This provides a level of protection against unauthorized transforms. Here is an example of generating a signed URI:
const crypto = require('crypto')
const secretToken = 'my-secret-token'
function sign (token, options, path) {
const hmac = crypto.createHmac('sha1', token)
hmac.update(`${options}/${path}`)
const signature = hmac.digest('hex')
return `${options}-signature:${signature}/${path}`
}
const signedFragment = sign(secretToken, 'width:100', 'path/to/image.jpg')