Skip to content
This repository has been archived by the owner on Sep 2, 2020. It is now read-only.


Folders and files

Last commit message
Last commit date

Latest commit



29 Commits

Repository files navigation


A very simple image hosting library

  • Serve images (originals and resized to preconfigured sizes) from configurable directory
  • Uses hapi
  • Requires either GraphicsMagick or ImageMagick. Please see gm docs for more info
  • Patterned after bumble

Add the module to your app

npm install fireball
var Hapi = require('hapi');
var config = require('./fireballConfig.json');

var server = new Hapi.Server('', 3000 || process.env.PORT);

server.pack.require({'fireball': config}, function (err) {
    if (err) throw err;
    server.start(function () {
        server.log(['info', 'fireball], 'fireball running on the year' +;

Set your defaults in fireballConfig.json

    "cache": 3600000,
    "baseURL": "/url/to/images",
    "imageDir": "path/to/images",
    "saveDir": "path/to/save/resized/images",
    "processing": [
            "suffix": "s",
            "action": "resize",
            "params": [256, null, ">"]
            "suffix": "m",
            "action": "resize",
            "params": [512, null, ">"]
            "suffix": "l",
            "action": "resize",
            "params": [1024, null, ">"]

cache: (integer, optional, default=3600000 (one hour)) Expiration time in milliseconds to send to the browser on request. Set to 0 to disable browser-cache headers.

baseURL: (string, optional, default=/fireball/) where the images will be served from

imageDir: (string, optional, default=images) local directory to look in for images. Subdirectories here will translate to the url of the images.

saveDir: (string, optional, default=fireballImages) where to save the processed images, will be created if missing.

processing: (object, optional, default=see below) defines the processing to do to images, key names here are added to the url of the original image. Currently only resize is supported.

reprocess: (boolean, optional, default=false) whether or not to reprocess all files in imageDir on startup regardless of if they have processed results in saveDir

Default processing

By default fireball will process images into three versions: s, m, and l with scaled widths of 256, 512, and 1024px respectively. If the original image is smaller than the processed version would be the original is kept.

Example urls:

Let's say you set baseURL to /pics and that you put an image named mycat.jpg in the configured imageDir. Given the above example, Fireball would then make that photo available at the following urls (assuming you were running off of localhost):


These would be the original, 256px wide, 512px wide, and 1024px wide versions of that image. Fireball will not increase the size of an image, if the resize is greater than the original, the original is used.


When reprocess is false (which it is by default), if a suffix has alread ran through a given processing action, it will not run again. This is great for startup times, but it means that if you change a processing rule for a given suffix, you will need to remove all the files from the saveDir for that suffix.


Image hosting library a la bumble






No packages published