Express middleware that processes served images according to the query string

Usage no npm install needed!

<script type="module">
  import expressProcessimage from '';



NPM version Build Status Coverage Status Dependency Status

Middleware that processes images according to the query string. It is intended to be used in a development setting with the static middleware, but should play well with any middleware further down the stack, even an http proxy, via hijackresponse.

Images are processed using the impro module which implements automatic switching between a number of image libraries based on the requested options.

Important note: This module is intended for development. While impro validates requested image operations, ultimately image data which could be untrusted in such use would be passed directly to various command line tools. In addition, extremely large images represent an attack surface unless restrictions on maximum input and output sizes are configured.


Make sure you have node.js and npm installed, then run:

npm install express-processimage

Query string syntax

express-processimage supports pngcrush, pngquant, optipng, jpegtran, inkscape, svgfilter, and all methods listed under "manipulation" and "drawing primitives" in the documentation for the gm module.

Multiple tools can be applied to the same image (separated by &, and the order is significant). Arguments for the individual tools are separated by non-URL encoded comma or plus.


Example usage

Express 3.0 syntax:

var express = require('express'),
  processImage = require('express-processimage'),
  root = '/path/to/my/static/files';

  .use(processImage({ root: root }))

From this point forward, the resposnes tp GET requests to port 1337 are matched by their Content-Type matched and in the case of an it will be processed by the image pipeline using options specified in query string. The processed output is delivered to the client.

Svg processing

The root option is used by node-svgfilter for finding the location of external JavaScript files to run on the SVG document.

Response processing

The response will be be processed under these circumstances:

  • If the request has a query string and accepts image/*.
  • If the response is served with a Content-Type of image/*.

express-processimage plays nice with conditional GET. If the original response has an ETag, express-processimage will add to it so the ETag of the processed image never clashes with the original ETag. That prevents the middleware issuing the original response from being confused into sending a false positive 304 Not Modified if express-processimage is turned off or removed from the stack later.

Development with Docker

Build the docker image by running:

$ npm run docker:build

Open the development environment:

$ npm run docker

The above command will place you in a bash shell where the working directory is your express-processimage checkout from your local machine. It is mounted into the container which is based on Ubuntu 14.04 and contains all the required dependencies, and nvm with the latest node 8 version active.

If you need to run the tests against another node version, you just have to change the version using nvm and reinstall your modules.

The environment is configured to resemble our setup on Travis CI as much as possible.


3-clause BSD license -- see the LICENSE file for details.