README.md

Sharp AWS image handler client

Note: this ES6 module needs to be transpiled for browser compatibility, using a tool like babel in your upstream project.

Docs

Prepares CDN image URL with appropriate filters relying on AWS image handler (v4) that leverages sharp. This lets you build CDN image URLs with sharp edit operations, such as resizing or WebP compression. https://docs.aws.amazon.com/solutions/latest/serverless-image-handler/deployment.html

Example

import { Cdn } from 'sharp-aws-image-handler-client'
const cdn = new Cdn({
 base: 'https://my-distribution.cloudfront.net/,
 bucket: 's3-bucket-name,
})

• sharp-aws-image-handler-client
  • .Cdn
    • new exports.Cdn()
    • .base : String
    • .bucket : String
    • .s3BucketUrl : String
    • .warnings : Boolean
    • .servedFromCdnBucket(uri, [base], [bucketUrl]) : function
  • .getUrl(uri, [edits], [options]) ⇒ String

cdn.Cdn

Kind: static class of sharp-aws-image-handler-client

• .Cdn
  • new exports.Cdn()
  • .base : String
  • .bucket : String
  • .s3BucketUrl : String
  • .warnings : Boolean
  • .servedFromCdnBucket(uri, [base], [bucketUrl]) : function

new exports.Cdn()

Instantiates class with CDN parameters

cdn.base : String

Base URL of CDN handling images, such as https://cdn.stelace.com

Kind: instance property of Cdn

cdn.bucket : String

Plain S3 bucket name such as 'my-files'

Kind: instance property of Cdn

cdn.s3BucketUrl : String

S3 bucket URL

Kind: instance property of Cdn
Read only: true

cdn.warnings : Boolean

Using console.warn for potential errors like non-ascii or special chars in S3 file key

Kind: instance property of Cdn
Default: true

cdn.servedFromCdnBucket(uri, [base], [bucketUrl]) : function

Lets you check that a file URI is served from CDN before trying to apply image edits in getUrl method. Can return:

• falsy value: getUrl(uri, edits) method will simply return uri and ignore edits.
• truthy value: getUrl(uri, edits) will build the URL with sharp edits.
• string: used as one-time bucket override in getUrl & having the same effect as a truthy value.

Kind: instance method of Cdn
Default: (uri, base, bucketUrl) => uri.startsWith(base) || uri.startsWith(bucketUrl)

Param	Type	Default	Description
uri	String		File uri can be an URL including host and protocol
[base]	String	cdn.base	Base URL of CDN handling images to check against
[bucketUrl]	String	cdn.s3BucketUrl	S3 bucket URL to check against

cdn.getUrl(uri, [edits], [options]) ⇒ String

Turns CDN file URI into image URL with edit operations. If uri is a full URL and the file is not served from CDN, uri is return unchanged.

Kind: static method of sharp-aws-image-handler-client
Returns: String - full URL with encoded edits

Param	Type	Default	Description
uri	String		File uri can be an URL including host and protocol.
[edits]	Object		only used if image is served from CDN with image handler. This object can include any sharp transform, like edits: { webp: true }.
[options]	Object
[options.bucket]	String	cdn.bucket	overriding default bucket and any bucket returned by servedFromCdnBucket method.

Example

import { Cdn } from 'sharp-aws-image-handler-client'
const cdn = new Cdn({
 base: 'https://my-distribution.cloudfront.net/,
 bucket: 's3-bucket-name
})

const url = cdn.getUrl('filename.jpg', {
  webp: true,
  resize: { width: 800, height: 600 }
})

Utility

testWebP

Tests asynchronously if WebP is supported by browser.

Kind: global function
Returns: Promise.<Boolean> - WebP support in current browser
Example

import { testWebP } from 'sharp-aws-image-handler-client'
const supportsWebP = await testWebP()

getSafeS3String

Make uri/filename safe for S3. https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html

Kind: global function
Returns: String - Safe string

Param	Type
string	String

Example

import { getSafeS3String } from 'sharp-aws-image-handler-client'
const unsafe = 'special~©harŝ éeè.png'
const safe = getSafeS3String(unsafe) // specialhar-e.png