search

andismith / grunt-responsive-images

Produce images at different sizes for responsive websites.
http://www.andismith.com/grunt-responsive-images/
MIT License
719 stars 96 forks source link
graphicsmagick grunt grunt-plugins imagemagick picturefill resizing-images responsive-images srcset

readme

grunt-responsive-images

NPM version Downloads Per Month Downloads Total

Produces images at different sizes

Please note - this project is no longer being maintained

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. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-responsive-images --save-dev

You also need to install either GraphicsMagick or Imagemagick CLI tools.

Installing GraphicsMagick (Recommended)

If you're a Mac user and have Homebrew installed, simply type:

brew install GraphicsMagick

Alternatively, you can try:

$ sudo add-apt-repository ppa:dhor/myway
$ sudo apt-get update
$ sudo apt-get install graphicsmagick

Otherwise, please visit the GraphicsMagick downloads page.

Or installing ImageMagick

If you're a Mac user and have Homebrew installed, simply type:

brew install ImageMagick

Otherwise, please visit the ImageMagick downloads page.

Once both the plugin and graphics engine have been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-responsive-images');

Back For More?

Check the release history at the bottom of this readme for what's changed!

The "responsive_images" task

Overview

Learn more about Grunt Responsive Images on the accompanying website.

The responsive_images task will take your source image and create images at different resolutions for use with PictureFill or with srcset.

A demo of both srcset and PictureFill using Grunt Responsive Images is available here.

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

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

Options

Custom input arguments as specified at https://github.com/aheckmann/gm#custom-arguments See example below.

Custom output arguments as specified at https://github.com/aheckmann/gm#custom-arguments See example below.

Usage Examples

Default Options

Using the default options will produce 3 responsive images - one at 320px wide, one at 640px wide and one at 1024px wide.

grunt.initConfig({
  responsive_images: {
    myTask: {
      options: {},
      files: {
        'dest/mario-yoshi.jpg': 'test/assets/mario-yoshi.jpg'
      }
    }
  }
})

Custom Options

In this example, we specify our own image sizes, including a retina graphic. We also specify our files with a wildcard.

grunt.initConfig({
  responsive_images: {
    myTask: {
      options: {
        sizes: [{
          width: 320,
          height: 240
        },{
          name: 'large',
          width: 640
        },{
          name: "large",
          width: 1024,
          suffix: "_x2",
          quality: 60
        }]
      },
      files: [{
        expand: true,
        src: ['assets/**.{jpg,gif,png}'],
        cwd: 'test/',
        dest: 'tmp/'
      }]
    }
  },
})

Custom Destination

If you would like to output each image size to a different directory, you can do so with custom_dest. For example:

grunt.initConfig({
  responsive_images: {
    myTask: {
      options: {
        sizes: [{
          width: 320,
        },{
          width: 640,
        },{
          width: 1024,
        }]
      },
      files: [{
        expand: true,
        src: ['**.{jpg,gif,png}'],
        cwd: 'test/assets/custom_dest/',
        custom_dest: 'tmp/custom_dest/{%= width %}/'
      }]
    }
  },
})

You can use {%= width %}, {%= height %}, {%= name %} or {%= path %} as a delimiter.

Please note that {%= width %}, {%= height %} and {%= name %} are only available if they are set in the object literal that you use to set each generated size option.

The {%= path %} value contains additional directory structure from the current working directory (cwd in files array) to each image. Using {%= path %} allows any complex directory structure to persist into the rendered responsive images directory.

NOTE: for grunt-responsive-images to pick up images within subdirectories you must set your files.src property to **/*.{jpg,gif,png}.

Custom Input/Output options

The options customIn and customOut pass additional arguments to the graphics engine. Refer to your graphics engine documentation for a full list of the possibilities. customIn places arguments after the convert command and before any other arguments, while customOut places arguments after any other arguments, but before the output file name.

grunt.initConfig({
  responsive_images: {
    myTask: {
      options: {
        customIn: ['-interlace', 'line'], // produce progressive images
        customOut: [
            // draw a copywrite notice in the bottom-right corner
            '-gravity', 'SouthEast', '-font', 'Arial', '-pointsize', '12',
            '-fill', '#445', '-draw', 'text 5,2 \'\u00A9 copywrite\'',
            '-fill', '#ffe', '-draw', 'text 6,3 \'\u00A9 copywrite\''
        ]
      },
      files: {
        'dest/mario-yoshi.jpg': 'test/assets/mario-yoshi.jpg'
      }
    }
  }
})

With gm this produces the command-line invocation:

gm "convert" "-interlace" "line" "-quality" "100" "test/assets/mario-yoshi.jpg" "-resize" "320x" "-gravity" "SouthEast" "-font" "Arial" "-pointsize" "12" "-fill" "#445" "-draw" "text 5,2 '© copyright'" "-fill" "#ffe" "-draw" "text 6,3 '© copyright'" "dest/mario-yoshi.jpg"

As Seen On...

The following sites and libraries are using Grunt Responsive Images (because they ROCK!):

And the inspiration for grunt-responsive-videos.

Also, the plugin grunt-responsive-images-extender is a fitting add-on to leverage your images in srcset and sizes attributes of your img tags.

Please let us know if your live site or library uses Grunt Responsive Images. We'll add our favorites.

FAQ

Release History

1.10.0

0.1.9

0.1.8

0.1.7

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

0.1.0

0.0.7

0.0.5

0.0.4

0.0.3

0.0.2

0.0.1

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Thanks to all the contributors who've submitted a pull request; and everyone who's raised issues or contributed to issue resolution.