grunt-spritesmith-hd

Uses grunt-spritesmith along with some image-manipulation and SCSS-trickery to generate HD-compatible sprites and corresponding SCSS stylesheets.

Requirements

grunt-spritesmith — allows for a variety of spriting engines (check out its requirements).

grunt-spritesmith-hd, though, is more restricted. It uses GraphicsMagick for Node for image processessing, and that requires that you already have either GraphicsMagick or ImageMagick installed. (Note that if you have installed ImageMagick and not GraphicsMagick, you need to specify this in the resizeEngine setting.)

Installation

This plugin requires Grunt ~0.4.0

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-spritesmith-hd --save-dev

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

grunt.loadNpmTasks('grunt-spritesmith-hd');

SpriteHD Task

Run this task with the grunt spriteHD command.

First, have a look at the configuration options available for grunt-spritesmith. Most of those relate to grunt-spritesmith-hd — except cssFormat and cssTemplate, since this plugin relies special SCSS.

(If you would like grunt-spritesmith-hd to be more flexible, please contribute!)

Unlike the original grunt-spritesmith, this plugin utilizes Grunt's options, so you can pass the same options to multiple targets.

Required Parameters

The following parameters must be defined for every target.

src

Type: String | Array

The assets that will be aggregated into your sprite.

spriteName

Type: String

A name that will designate your sprite's files.

For example, if you were to provide the spriteName "genuflect", your sprite images would end up as hd-genuflect.png and ld-genuflect.png and your stylesheets would be _sprite-genuflect.scss and _sprite-genuflect-hd.scss.

Options

As with other Grunt tasks, these options can be task-wide or target-specific.

All of these options are optional, because they all either have default values or can be ignored.

hd

Type: Boolean Default: true

Do you want your spritesheet high-def-ready? Are your sprite assets 2x the size that they will appear?

Set to false if your sprite assets aren't up for it.

If hd is false, grunt-spritesmith-hd will simply run grunt-spritesmith with the parameters and options you've passed.

destImg

Type: String Default: images/sprites

A directory where your generated sprite image(s) will go.

destCSS

Type: String Default: style/scss/sprites

A directory where your generated SCSS file(s) will go.

hdPrefix

Type: String Default: hd

A prefix for your high-def sprite files.

ldPrefix

Type: String Default: ld

A prefix for your low-def sprite files.

resizeEngine

Options: gm, im Default: gm

The engine that will be used behind-the-scenes for resizing. Defaults to GraphicsMagick; but if you only have ImageMagick installed and want to use that, instead, specify it here.

algorithm

Options: top-down, left-right, diagonal, alt-diagonal, binary-tree Default: binary-tree

A packing algorithm to use. See details in grunt-spritesmith's documentation.

algorithmOpts

See details in grunt-spritesmith's documentation.

padding

Type: Number Default: 1

Padding to be placed between images on the generated spritesheet(s).

engine

Options: auto, phantomjs, canvas, gm Default: gm

Specify your spritesmith engine. See details in grunt-spritesmith's documentation.

engineOpts

Type: Object Default: {}

Specify settings for your engine. See details in grunt-spritesmith's documentation.

imageOpts

Type: Object Default: {}

Specify image processing options. See details in grunt-spritesmith's documentation.

assetFormats

Type: Array Default: ['.png', '.jpg', '.jpeg']

Accepted extensions for your sprite assets.

imgPath

Type: String Default: The default value is the relative path between your destCSS and destImg directories.

Manually override the sprite image's path in the generated stylesheet's background-image url(s). Here are a couple of use cases:

• If the relative path from your destCSS directory (where the SCSS files go) to your destImg directory (where your sprite images go) will not be the same as the relative path from your compiled CSS to destImg.
• If you will be hosting the images elsewhere, eventually, on a CDN or something.

cssOpts

Type: Object Default: {}

Options to pass to the Mustache template that generates your stylesheets.

• { functions: false }: the generated SCSS includes variables only, not mixins. This is handy if you are using multiple sprites in a project and don't want to duplicate the mixin definitions.
• { createMap: false }: If true, will create a variabble map in the SCSS file
• { varPrefix: none }: String value to set a prefix for the variables in the generated SCSS

failOnOddImageSize

Type: Boolean Default: false

Set it to true in order to interrupt the build process if any of the standard source images size (width or height) is not even.

If it's set to false the build process just raise a warning.

All the images should have an even height and an even width (e.g. 22x26px)

ldCssTemplate

Type: String Default: undefined

The default results in the use of the default template for the scss extension of json2css. You can pass a path to a template that is then passed to grunt-spritesmith as the cssTemplate option. The path can be relative to the directory where you call grunt or relative to the tasks directory of grunt-spritesmith-hd.

hdCssTemplate

Type: String Default: path.join(__dirname, 'templates/scss-hd.template.mustache')

If you don't pass this option, the scss-hd.template.mustache from grunt-spritesmith-hd is used. You can pass a path to a template that is then passed to grunt-spritesmith as the cssTemplate option. The path can be relative to the directory where you call grunt or relative to the tasks directory of grunt-spritesmith-hd.

Examples

Basic:

spriteHD: {
  options: {
    destImg: "sprites",
    destCSS: "scss/sprites",
    imgPath: "sprites"
  }
  all {
    src: ["images/sprite-assets/all/*"],
    spriteName: "all"
  }
  home: {
    src: ["images/sprite-assets/home/*"],
    spriteName: "home",
    options: {
      cssOpts: {
        functions: false,
        createMap: true,
        varPrefix: 'icon-medium'
      }
    }
  }
}

combined scss maps:

This uses the template at https://github.com/benib/json2css_scss_combined_maps

spriteHD: {
  options: {
    destImg: "sprites",
    destCSS: "scss/sprites",
    imgPath: "sprites",
    hdCssTemplate: 'node_modules/json2css_scss_combined_maps/scss_combined_maps.template.mustache',
    ldCssTemplate: 'templates/scss_combined_maps-hd.template.mustache'
  }
  all {
    src: ["images/sprite-assets/all/*"],
    spriteName: "all"
  }
  home: {
    src: ["images/sprite-assets/home/*"],
    spriteName: "home",
    options: {
      cssOpts: {
        functions: false
      }
    }
  }
}

Using the Output

After running grunt-spritesmith-hd, in your destCSS directory you will find an unprefixed SCSS file — that is the one you should import into your own SCSS/Sass.

For example, a typical HD sprite with the spriteName "everything" will output _everything-hd.scss and _everything.scss into destCSS. You need to @import "path/to/everything".

(If you look inside _everything.scss, you'll see that already imports _everything-hd.scss, so you don't have to worry about it.)