by arminnaami


Image Proxy

NPM version Build Status Dependency Status Coverage Status

A simple Express app for proxying and manipulating images, specifically headshots.

The code is just over 100 lines, making it easy to tailor to your needs.

Getting Started

First, install the dependencies for the gm package.

npm install
npm start
curl -I http://localhost:5000/

The URL structure is /:url/:width/:height.:extension?. The :url parameter must be escaped/encoded. If the remote image's width or height is greater than the given :width or :height, it will be resized, maintaining aspect ratio, and cropped. If smaller, it will be padded with white pixels. If an optional :extension parameter is provided, the image will be transcoded to the corresponding file format. The equivalent ImageMagick command for the example URL above is:

convert input.jpg -thumbnail 240x80^> -gravity center -extent 240x80 output.jpg

The Cache-Control header sets a max-age of one year.


Image proxy:

  • Supports HTTP and HTTPS
  • Follows 301 and 302 redirects
  • Sets a maximum timeout for the remote server
  • Handles complex MIME types like image/jpeg; charset=utf-8
  • Optional whitelisting using regular expressions

Image manipulation:

  • Accepts a custom width and height, up to 1000x1000
  • Resizes, centers and crops the image
  • Optionally transcodes to another file format

HTTP server:

  • No query string parameters (preferred by CloudFront)
  • Adds a Cache-Control header

If you need more features, see node-imageable and node-imageable-server.

Environment variables

  • DELAY: The timeout delay in milliseconds, after which the proxy will respond with a HTTP 504 Gateway Timeout server error. Default: 5000
  • WHITELIST: A comma-separated list of domains to whitelist, e.g. .gov,, which will be transformed into the regular expressions /\.gov$/ and /facebook\.com$/.
  • PORT: If running the server, changes the port on which it listens. Default: 5000




git clone
heroku apps:create
heroku config:set NODE_ENV=production
git push heroku master
heroku apps:open

AWS CloudFront

Create a distribution and set the "Origin Domain Name" to the domain name of your Heroku app.


npm test


This project is inspired by node-connect-image-proxy.

Copyright (c) 2013 James McKinney, released under the MIT license