node-spritesheet

Node-spritesheet is a utility to create sprite sheets in node.js. Its original
intention was to be used as a Grunt task,
but I decided it was worth abstracting further.

In the most part, it is an indirect port of
Jake Gordon's much more mature
Sprite Factory for Ruby.

Pixel ratios (retina displays, etc)

It will also handle auto-resizing of images for specified pixel
densities. No more fart-arsing about for retina displays, just supply the
largest (highest-density) image. By default, this uses ImageMagick's version of
the Lanczos and Mitchell algorithms, depending on the most appropriate, but you
can specify any of the 20-odd available.

You're not locked in to auto-resampling though, you can supply multiple density
versions of the same image, if you prefer.

Additionally, it will add the relevant cross-browser media queries to the CSS.

Requirements

Requires ImageMagick. For Unix/Mac, this will
be installed automagickally (ouch).

Installation

npm install node-spritesheet

Usage

var Builder = require( 'node-spritesheet' ).Builder;
var b = new Builder( options );
b.build( callback );

$3

Takes in a series of images a generates a spritesheet.

var Builder = require( 'node-spritesheet' ).Builder;

var builder = new Builder({
outputDirectory: '/path/to/directory',
outputImage: 'sprite.png',
outputCss: 'sprite.css',
selector: '.sprite',
images: [ 'image1.png', 'image2.png', image3.png' ]
});

builder.build( function() {
console.log( "Built from " + builder.images.length + " images" );
});

$3

Add configurations to the builder to output multiple spritesheets based on
different pixel densities, using media queries.

var Builder = require( 'node-spritesheet' ).Builder;

var builder = new Builder({
outputDirectory: '/path/to/directory',
outputCss: 'sprite.css',
selector: '.sprite',
images: [ 'image1.png', 'image2.png', image3.png' ]
});

builder.addConfiguration( "legacy", {
pixelRatio: 1,
outputImage: 'sprite.png'
});

builder.addConfiguration( "retina", {
pixelRatio: 2,
outputImage: 'sprite@2x.png'
});

builder.build( function() {
console.log( "Built from " + builder.images.length + " images" );
});

$3

Even though ImageMagick uses some pretty decent algorithms for resampling images,
you may not want node-spritesheet to automatically resize your retina versions
for you, you may want to instead keep two copies of each image.

var Builder = require( 'node-spritesheet' ).Builder;

var builder = new Builder({
outputDirectory: '/path/to/directory',
outputCss: 'sprite.css',
selector: '.sprite'
});

builder.addConfiguration( "legacy", {
pixelRatio: 1,
outputImage: 'sprite.png',
images: [ 'image1.png', 'image2.png', image3.png' ]
});

builder.addConfiguration( "retina", {
pixelRatio: 2,
outputImage: 'sprite@2x.png',
images: [ 'image1@2x.png', 'image2@2x.png', image3@2x.png' ]
});

builder.build( function() {
console.log( "Built from " + builder.images.length + " images" );
});

Grunt task

This is a multi-task, supporting multiple spritesheets in one gruntfile.

The following grunt.js structure takes all images in src/icons and creates
a spritesheet at bin/assets/sprite.png, with an accompanying stylesheet at
bin/assets/sprite.css.

$3

// Add to your grunt config.
spritesheet: {
compile: {
options: {
// Compiles to bin/assets/images/spritesheets/flags.png
outputImage: 'images/spritesheets/flags.png',
// Compiles to bin/assets/stylesheets/flags.css
outputCss: 'stylesheets/flags.css',
// Uses this compound selector in the css, e.g. '.flag.my-image {}'
selector: '.flag'
},
files: {
'bin/assets': 'src/icons/flags/*'
}
}
}

// Add to your imports.
loadNpmTasks( 'node-spritesheet' );

$3

This adds retina/legacy support, and resamples the images (assuming the
highest density has been supplied).

// Add to your grunt config.
spritesheet: {
compile: {
options: {
outputCss: 'sprite.css',
selector: '.sprite',
// Optional ImageMagick sampling filter.
downsampling: "LanczosSharp",
// Output configurations: in this instance to output two sprite sheets,
// one for "legacy" (i.e. 72dpi, pixel ratio 1), and "retina" (x2).
// These keys (legacy, retina) are completely arbitrary.
output: {
legacy: {
pixelRatio: 1,
outputImage: 'sprite.png'
},
// As the retina scheme has the highest pixel ratio, it will be
// assumed that all images passed to the builder are for 'retina',
// and will be downscaled for 'legacy'.
retina: {
pixelRatio: 2,
outputImage: 'sprite@2x.png'
}
},
// Allows you to augment your selector names for each image, based on
// the bare image "name", or the full image path.
resolveImageSelector: function( name, fullpath ) {
// For example, your files may well already be named with @2x, but
// you won't want that included in your CSS selectors.
return name.split( "@2x" ).join( "" );
}
},
files: {
'bin/assets': 'src/icons/flags/*'
}
}
}

// Add to your imports.
loadNpmTasks( 'node-spritesheet' );

$3

Again, this adds retina/legacy support, but uses a filter function to ascertain
which images are retina and which aren't, meaning you don't have to rely on the
resampling option, if you want finer control.

// Add to your grunt config.
spritesheet: {
compile: {
options: {
outputCss: 'sprite.css',
selector: '.sprite',
output: {
legacy: {
pixelRatio: 1,
outputImage: 'sprite.png',
// Just process the non-retina files
filter: function( fullpath ) {
return fullpath.indexOf( "@2x" ) === -1;
}
},
retina: {
pixelRatio: 2,
outputImage: 'sprite@2x.png',
// Just process the retina files
filter: function( fullpath ) {
return fullpath.indexOf( "@2x" ) >= 0;
}
}
}
},
files: {
'bin/assets': 'src/icons/flags/*'
}
}
}

// Add to your imports.
loadNpmTasks( 'node-spritesheet' );