gulp.spritesmith

gulp.spritesmith

Convert a set of images into a spritesheet and CSS variables via gulp

This is the official port of grunt-spritesmith, the grunt equivalent of a wrapper around spritesmith.

Alternative output formats include SASS, Stylus, LESS, and JSON.

Getting Started

Install the module with: npm install gulp.spritesmith

var gulp = require('gulp');
var spritesmith = require('gulp.spritesmith');

gulp.task('sprite', function () {
  var spriteData = gulp.src('images/*.png').pipe(spritesmith({
    imgName: 'sprite.png',
    cssName: 'sprite.css'
  }));
  spriteData.img.pipe(gulp.dest('path/to/image/folder/'));
  spriteData.css.pipe(gulp.dest('path/to/css/folder/'));
});

Documentation

gulp.spritesmith presents the spritesmith function as its module.exports.

spritesmith(params)

gulp plugin that returns a readable stream and an object containing two writable streams.

The input/output streams interact with vinyl-fs objects which are gulp's format of choice.

• params Object - Container for gulp.spritesmith parameters
  • imgName String - Filename to save image as
    • Supported image extensions are .png and .jpg/jpeg (limited to specfic engines)
    • Image format can be overridden via imgOpts.format
  • cssName String - Filename to save CSS as
    • Supported CSS extensions are .css (CSS), .sass (SASS), .scss (SCSS), .less (LESS), .styl/.stylus (Stylus), and .json (JSON)
    • CSS format can be overridden via cssFormat
  • imgPath String - Optional path to use in CSS referring to image location
  • engine String - Optional image generating engine to use
    • By default, auto will be used which detects the best supported engine for your system
    • Supported options are phantomjs, canvas, gm, and pngsmith
    • More information can be found in the engine section
  • algorithm String - Optional method for how to pack images
    • Supported options are top-down (default), left-right, diagonal, alt-diagonal, and binary-tree
    • More information can be found in the algorithm section
  • padding Number - Optional amount of pixels to include between images
    • By default, there will be no padding
  • imgOpts Object - Options for image output
    • format String - Override for format of output image
      • Supported values are png and jpg (limited to specific engines)
    • quality Number - Quality of image (only supported by gm engine)
    • timeout Number - Milliseconds to wait before terminating render (limited to phantomjs engine)
  • algorithmOpts Object - Options for algorithm configuration
    • sort Boolean - Enable/disable image sorting by algorithm
      • By default, sorting is enabled (true)
  • engineOpts Object - Options for engine configuration
    • imagemagick Boolean - Force usage of imagemagick over graphicsmagick (limited to gm)
  • cssFormat String - Override for format of CSS output
    • Supported values are css (CSS), sass (SASS), scss (SCSS), scss_maps (SCSS using map notation), less (LESS), stylus (Stylus), and json (JSON)
  • cssVarMap Function - Iterator to customize CSS variable names
    • An example can be found here
  • cssTemplate Function|String - CSS templating function or path to alternative mustache template
    • More information can be found in the cssTemplate section
  • cssOpts Object - Container for CSS templates
    • functions Boolean - Skip output of mixins
    • cssClass Function - Iterator to override default CSS selectors
      • An example can be found here

Engines

For cross-platform accessibility, spritesmith offers multiple sprite engines. Each of these engines has a different set of dependencies.

If you are running into issues, consult the FAQ section.

pngsmith

The pngsmith engine uses pngparse, an JavaScript png parser, to interpret images into ndarrays. This requires no additional steps before installation.

Key differences: It requires no additional installation steps but you are limited to .png files for your source files.

phantomjs

The phantomjs engine relies on having phantomjs installed on your machine. Visit the phantomjs website for installation instructions.

spritesmith has been tested against phantomjs@1.9.0.

Key differences: phantomjs is the easiest engine to install that supports all image formats.

canvas

The canvas engine uses node-canvas which has a dependency on Cairo. Installation instructions can be found in the node-canvas wiki.

Additionally, you will need to install node-gyp for the C++ bindings.

npm install -g node-gyp

Key differences: canvas has the best performance (useful for over 100 sprites). However, it is limited to UNIX.

gm (Graphics Magick / Image Magick)

The gm engine depends on Graphics Magick or Image Magick.

For the best results, install from the site rather than through a package manager (e.g. apt-get). This avoids potential transparency issues which have been reported.

spritesmith has been developed and tested against graphicsmagick@1.3.17.

Key differences: gm has the most options for export via imgOpts.

Algorithms

spritesmith offers a variety of image patterns via [twolfson/layout][].

[twolfson/layout]: (https://github.com/twolfson/layout

top-down (default)	left-right	diagonal	alt-diagonal	binary-tree

For best packing, use binary-tree which uses a solution to the rectangle packing problem.

If you are worried about sprites being visible within other sprites, use alt-diagonal.

If you are using a repeating background, top-down or left-right depending on your occasion.

The diagonal algorithm exists for you if you need it.

cssTemplate

gulp.spritespritesmith allows you to define your own CSS template, either via a function or mustache template.

If you pass in a Function, it should have a signature of function (params) {} and return a String.

If you pass in a String, we treat this as a path; reading in the file and rendering it via mustache.js. The template will be passed the same params as in the Function case.

An example template is https://github.com/twolfson/json2css/blob/4.2.0/lib/templates/stylus.template.mustache

params

params is an object with some normalization nicities from json2css, our default collection of templates.

• params Object
  • items Object[] - Array of sprite information
    • name String - Name of the sprite file (sans extension)
    • x Number - Horizontal position of sprite's left edge in spritesheet
    • y Number - Vertical position of sprite's top edge in spritesheet
    • width Number - Width of sprite
    • height Number - Height of sprite
    • total_width Number - Width of entire spritesheet
    • total_height Number - Height of entire spritesheet
    • image String - Relative URL path from CSS to spritesheet
    • escaped_image String - URL encoded image
    • source_image String - Path to the original sprite file
    • offset_x Number - Negative value of x. Useful to background-position
    • offset_y Number - Negative value of y. Useful to background-position
    • px Object - Container for numeric values including px
      • x String - x suffixed with px
      • y String - y suffixed with px
      • width String - width suffixed with px
      • height String - height suffixed with px
      • total_width String - total_width suffixed with px
      • total_height String - total_height suffixed with px
      • offset_x String - offset_x suffixed with px
      • offset_y String - offset_y suffixed with px
  • options Object - Options passed in via cssOpts in grunt-spritesmith config

An example sprite item is:

{
  "name": "sprite2",
  "x": 10,
  "y": 20,
  "width": 20,
  "height": 30,
  "total_width": 80,
  "total_height": 100,
  "image": "nested/dir/spritesheet.png",
  "escaped_image": "nested/dir/spritesheet.png",
  "source_image": "path/to/original/sprite.png",
  "offset_x": -10,
  "offset_y": -20,
  "px": {
    "x": "10px",
    "y": "20px",
    "width": "20px",
    "height": "30px",
    "total_width": "80px",
    "total_height": "100px",
    "offset_x": "-10px",
    "offset_y": "-20px"
  }
}

Examples

Using cssVarMap

Task configuration:

gulp.task('sprite', function () {
  var spriteData = gulp.src('images/*.png').pipe(spritesmith({
    imgName: 'sprite.png',
    cssName: 'sprite.styl',
    cssVarMap: function (sprite) {
      // `sprite` has `name`, `image` (full path), `x`, `y`
      //   `width`, `height`, `total_width`, `total_height`
      // EXAMPLE: Prefix all sprite names with 'sprite-'
      sprite.name = 'sprite-' + sprite.name;
    }
  }));
  spriteData.img.pipe(gulp.dest('path/to/image/folder/'));
  spriteData.css.pipe(gulp.dest('path/to/styl/folder/'));
});

CSS output:

/* As opposed to `$fork_x = 0px;` */
$sprite-fork_x = 0px;
$sprite-fork_y = 0px;
$sprite-fork_offset_x = 0px;
$sprite-fork_offset_y = 0px;
...

Using cssOpts.cssClass

Task configuration:

gulp.task('sprite', function () {
  var spriteData = gulp.src('images/*.png').pipe(spritesmith({
    imgName: 'sprite.png',
    cssName: 'sprite.css',
    cssOpts: {
      cssClass: function (item) {
        // `item` has `x`, `y`, `width`, `height`, `name`, `image`, and more
        // It is suggested to `console.log` output
        return '.sprite-' + item.name;
      }
    }
  }));
  spriteData.img.pipe(gulp.dest('path/to/image/folder/'));
  spriteData.css.pipe(gulp.dest('path/to/css/folder/'));
});

CSS output:

/* As opposed to .fork { */
.sprite-fork {
  background-image: url(sprite.png);
  background-position: 0px 0px;
  width: 32px;
  height: 32px;
}

FAQs

I am seeing errors during installation.

If npm exits normally, everything should work. These errors are being caused by npm attempting to install the various spritesmith engines.

spritesmith is saying my engine "could not be loaded"

If you have specified an engine in your config, then you must satisfy its requirements before installing gulp.spritesmith.

To remedy this, verify you have installed the appropriate set of requirements for your engine:

https://github.com/twolfson/gulp.spritesmith#engines

Afterwards, re-install gulp.spritesmith so it detects the satisfied requirements for your engine.

npm install gulp.spritesmith

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 via gulp and test via npm test.

Attribution

GitHub and Twitter icons were taken from Alex Peattie's JustVector Social Icons.

Fork designed by P.J. Onori from The Noun Project.

Donating

Support this project and others by twolfson via gittip.

Unlicense

As of Feb 09 2014, Todd Wolfson has released this repository and its contents to the public domain.

It has been released under the UNLICENSE.