grunt-respimg

A responsive image workflow for optimizing and resizing your images.

This plugin will:

Efficiently resize PNGs, JPEGs, and non-animated GIFs to widths that you specify
Rasterize SVGs and PDFs to PNGs at widths that you specify
Optimize all your input and output images (PNGs, JPEGs, GIFs, and SVGs)

The output images should be visually indistinguishable from those output by Photoshop’s Save for Web…, but with (much) smaller average file sizes.

This plugin is heavily indebted to (and has portions borrowed liberally from):

Getting Started

This plugin requires Grunt ~0.4.5.

If you haven’t used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.

Installing ImageMagick

To use this grunt task, you’ll need to have ImageMagick installed. If you want this grunt task to be able to rasterize PDFs, you’ll need to install it with GhostScript support.

If you’re using a Mac with Homebrew, you can install ImageMagick like this:

brew install imagemagick --with-ghostscript

If you don’t have a Mac or aren’t using Homebrew, you should be able to find ImageMagick in your favourite package manager, or download it from the ImageMagick site.

Installing image optimizers

If you plan to use image optimization with this plugin (which I recommend you do, and which is the default), you’ll probably to install the image optimizers first. With this plugin you can use image_optim, picopt, and/or ImageOptim. Unfortunately, installing them can be a bit…complicated.

If you’re not able to get these working, or if you don’t care about image optimization, you can turn optimization off by setting optimize: false in your Gruntfile options:

respimg: {
    nooptim: {
        options: {
            optimize: false
        },
        files: [{
            expand: true,
            cwd: 'path/to/input',
            src: ['raster/**.{jpg,gif,png,svg,pdf}'],
            dest: 'path/to/output'
        }]
    }
}

These installation assumptions assume you’re on a Mac, but the instructions should be relatively similar for Linux systems as well. I’m not sure about Windows:

First, download and install pngout. To install pngout, you’ll need to move it to somewhere in your PATH. E.g.,

mv ~/Downloads/pngout-20150319-darwin/pngout /usr/local/bin/

Then, download and install ImageOptim (Mac only). To install ImageOptim, decompress the .tbz2 file you downloaded from the site, and drag the ImageOptim.app to your Applications folder.

Using your favorite package manager (e.g. Homebrew on OS X), install cairo, optipng, jpeg, and gifsicle:

brew install cairo optipng jpeg gifsicle

Using gem (the Ruby gem package manager), install image_optim and image_optim_pack:

gem install image_optim image_optim_pack

If you get a permissions error, you may need to use sudo.

sudo gem install image_optim image_optim_pack

Using pip (a Python package manager), install picopt:

pip install picopt

If you’re on a Mac, the Cairo install may be a bit wonky, so you may need to do this:

export PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig

Installing the plugin

Once you’ve installed the optimizers (or if you’re not going to do optimization), you may install this plugin with this command:

npm install grunt-respimg --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-respimg');

The “respimg” task

Overview

In your project’s Gruntfile, add a section named respimg to the data object passed into grunt.initConfig().

grunt.initConfig({
  respimg: {
    options: {
      // Task-specific options go here. 
    },
    your_target: {
      // Target-specific file lists go here. 
    },
  },
});

Options you should care about

The only option you should really care about setting is widths:

options.widths

Type: int[]
Default value: [ 320, 640, 1280 ]

The widths that images should be resized to.

options.widthAsDir

Type: bool
Default value: false

Save resized images under a directory with the same name of the width instead adding the width to the filename.

options.optimize

Type: false, object

When multiple programs are used for optimization, they are run in the following order:

svgo
image_optim
picopt
ImageOptim

Note: options.optimize.svg, options.optimize.rasterInput, and options.optimize.rasterOutput are deprecated, but should still work. Please switch your syntax to use the new optimize options below.