express-sharp

express-sharp

express-sharp adds real-time image processing routes to your express application. Images are processed with sharp, a fast Node.js module for resizing images.

                      express-sharp
    Express app         endpoint          image path    transformation                
┌─────────────────┐┌────────────────┐┌──────────────────┐ ┌────────┐
https://example.com/path/to/my-scaler/images/my-image.jpg?w=100&h=50

Original images are loaded via an image adapter. Currently this includes HTTP and file system adapters.

• Installation
• Express server integration
  • Server configuration
  • Image Adapters
    • FsAdapter
    • HttpAdapter
• Client integration
• License

Installation

$ yarn add express-sharp

See sharp installation for additional installation instructions.

Express server integration

Example app.js (See also example/app.ts in this project):

const express = require('express')
const app = express()
const { expressSharp, FsAdapter, HttpAdapter } = require('express-sharp')

// Fetch original images via HTTP
app.use(
  '/some-http-endpoint',
  expressSharp({
    imageAdapter: new HttpAdapter({
      prefixUrl: 'http://example.com/images',
    }),
  })
)

// Alternative: Load original images from disk
app.use(
  '/fs-endpoint',
  expressSharp({
    cache,
    imageAdapter: new FsAdapter(path.join(__dirname, 'images')),
  })
)

app.listen(3000)

Render /images/image.jpg with 400x400 pixels:

curl http://my-server/express-sharp-endpoint/images/image.jpg?w=400&h=400

Same as above, but with 80% quality, webp image type and with progressive enabled:

curl http://my-server/express-sharp-endpoint/images/image.jpg?w=400&h=400&f=webp&q=80&p

Server configuration

const scale = require('express-sharp')
app.use('/some-http-endpoint', expressSharp(options))

Supported options:

Name	Description	Default
imageAdapter	Configures the image adapter to be used (see below). Must be specified.	-
autoUseWebp	Specifies whether images should automatically be rendered in webp format when supported by the browser.	true
cors	Any valid CORS configuration option	-
cache	If specified, the keyv cache configured here is used to cache the retrieval of the original images and the transformations.	-

Image Adapters

express-sharp contains the following two standard image adapters.

FsAdapter

With this adapter original images are loaded from the hard disk.

const { FsAdapter } = require('express-sharp')

const adapter = new FsAdapter('/path/to/images')

HttpAdapter

Loads original images via HTTP.

const { HttpAdapter } = require('express-sharp')

const adapter = new HttpAdapter({
  prefixUrl: 'http://localhost:3000/images',
})

The constructor can be passed any got options.

Client integration

express-sharp comes with a client that can be used to generate URLs for images.

const { createClient } = require('express-sharp')

const client = createClient('http://my-base-host', 'optional secret')

const originalImageUrl = '/foo.png'
const options = { width: 500 }
const fooUrl = client.url(originalImageUrl, options)

Currently the following transformations can be applied to images:

Client option name	Query param name	Description
quality	q	Quality is a number between 1 and 100 (see sharp docs).
width	w
height	h
format	f	Output image format. Valid values: every valid sharp output format string, i.e. jpeg, gif, webp or raw.
progressive	p	Only available for jpeg and png formats. Enable progressive scan by passing true.
crop	c	Setting crop to true enables the sharp cropping feature. Note: Both width and height params are neccessary for crop to work. Default is false.
gravity	g	When the crop option is activated you can specify the gravity of the cropping. Possible attributes of the optional gravity are north, northeast, east, southeast, south, southwest, west, northwest, center and centre. Default is center.

License

MIT