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.

Retina support

As of gulp.spritesmith@3.5.0, retina spritesheets/templates are supported. See the Retina parameters section for more information.

Do you like gulp.spritesmith?

Support us via donations or spread word on Twitter

Breaking changes in 4.0.0

We are normalizing sprite variables even further to convert any non-alphanumeric/non-dash/non-underscore character to a delimiter character (e.g. -). This allows us to support naming retina sprites with @2x suffixes, to prevent regressions like grunt-spritesmith#137.

Breaking changes in 5.0.0

We have moved from spritesmith-engine-spec@1.1.0 to spritesmith-engine-spec@2.0.0. This means if you use an custom engine (e.g. gmsmith, canvassmith), then you will need to upgrade it.

npm install my-engine-smith@latest --save-dev

This is enables us to use streaming outputs from engines in a future release.

Additionally, we have added support for buffer and stream content for in-memory engines (e.g. pixelsmith, canvassmith) which resolves #53.

Breaking changes in 6.0.0

We have completed our integration with streaming outputs from engines. As a result, Vinyl img files will have stream contents which were previously buffers.

If your img pipeline requires Buffer contents, then this can be remedied via vinyl-buffer:

// Throws error due to not supporting streams
spriteData.img.pipe(imagemin());

// Back to operational
var buffer = require('vinyl-buffer');
spriteData.img.pipe(buffer()).pipe(imagemin());

Note for Gulp 5.0.0 upgrades

Gulp 5.0.0 introduced default encodings for src and dest streams of utf8.

Since gulp.spritesmith inputs and outputs images, we need to set {encoding: false} for the image .src() and .dest() streams.

See "Getting Started" for an hands-on example.

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', {encoding: false}).pipe(spritesmith({
    imgName: 'sprite.png',
    cssName: 'sprite.css'
  }));
  return spriteData.pipe(gulp.dest('path/to/output/', {encoding: false}));
});

Continuing the pipeline

In addition to the spriteData stream, we offer individual streams for images and CSS. This allows for image optimization and CSS minification.

var gulp = require('gulp');
var buffer = require('vinyl-buffer');
var csso = require('gulp-csso');
var imagemin = require('gulp-imagemin');
var merge = require('merge-stream');

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

gulp.task('sprite', function () {
  // Generate our spritesheet
  var spriteData = gulp.src('images/*.png', {encoding: false}).pipe(spritesmith({
    imgName: 'sprite.png',
    cssName: 'sprite.css'
  }));

  // Pipe image stream through image optimizer and onto disk
  var imgStream = spriteData.img
    // DEV: We must buffer our stream into a Buffer for `imagemin`
    .pipe(buffer())
    .pipe(imagemin())
    .pipe(gulp.dest('path/to/image/folder/', {encoding: false}));

  // Pipe CSS stream through CSS optimizer and onto disk
  var cssStream = spriteData.css
    .pipe(csso())
    .pipe(gulp.dest('path/to/css/folder/'));

  // Return a merged stream to handle both `end` events
  return merge(imgStream, cssStream);
});

Documentation

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

spritesmith(params)

gulp plugin that returns a transform stream with 2 readable stream properties.

The input/output streams interact with Vinyl 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
  • padding Number - Optional amount of pixels to include between images
    • By default we use no padding between images (0)
    • An example usage can be found in the Examples section
  • algorithm String - Optional method for how to pack images
    • By default we use binary-tree, which packs images as efficiently as possible
    • An example usage can be found in the Examples section
    • More information can be found in the Algorithms section
  • algorithmOpts Object - Options to pass through to algorithm
    • For example we can skip sorting in some algorithms via {algorithmOpts: {sort: false}}
      • This is useful for sprite animations
    • See your algorithm's documentation for available options
      • https://github.com/twolfson/layout#algorithms
  • engine String - Optional image generating engine to use
    • By default we use pixelsmith, a node based engine that supports all common image formats
    • Alternative engines must be installed via npm install
    • An example usage can be found in the Examples section
    • More information can be found in the Engines section
  • engineOpts Object - Options to pass through to engine for settings
    • For example phantomjssmith accepts timeout via {engineOpts: {timeout: 10000}}
    • See your engine's documentation for available options
  • imgOpts Object - Options to pass through to engine uring export
    • For example gmsmith supports quality via {imgOpts: {quality: 75}}
    • See your engine's documentation for available options
  • cssFormat String - CSS format to use
    • By default this is the format inferred by cssName's extension
      • For example .styl -> stylus
    • For more format options, see our formatting library
      • https://github.com/twolfson/spritesheet-templates#templates
  • cssTemplate String|Function - CSS template to use for rendering output CSS
    • This overrides cssFormat
    • If a String is provided, it must be a path to a handlebars template
      • An example usage can be found in the Examples section
    • If a Function is provided, it must have a signature of function (data)
      • An example usage can be found in the Examples section
    • For more templating information, see the Templating section
  • cssHandlebarsHelpers Object - Container for helpers to register to handlebars for our template
    • Each key-value pair is the name of a handlebars helper corresponding to its function
    • For example, {half: function (num) { return num/2; } will add a handlebars helper that halves numbers
  • cssVarMap Function - Mapping function for each filename to CSS variable
    • For more information, see Variable mapping
  • cssSpritesheetName String - Name to use for spritesheet related variables in preprocessor templates
  • cssOpts Object - Options to pass through to templater
    • For example {cssOpts: {functions: false}} skips output of mixins
    • See your template's documentation for available options
      • https://github.com/twolfson/spritesheet-templates#templates

Returns:

• spriteData stream.Transform - Stream that outputs image and CSS as Vinyl objects
• spriteData.img stream.Readable - Stream for image output as a Vinyl object
  • contents will be a Stream