Todd Wolfson

Software Engineer

March 11, 2013

grunt-spritesmith is a grunt plugin takes in paths to sprites and outputs a spritesheet and CSS pre-processor variables.

  'sprite': {
    'all': {
      // Sprite files to read in
      'src': ['public/images/sprites/*.png'],

      // Location to output spritesheet
      'destImg': 'public/images/sprite.png',

      // Stylus with variables under sprite names
      'destCSS': 'public/css/sprite_positions.styl'


grunt-spritesmith is composed of 5 separate modules. Each of them was built to be extensible at run-time.

  • grunt-spritesmith -- What you were shown above
  • spritesmith -- Reads in sprites and composes spritesheet
  • layout -- Handles positioning of images and multiple algorithmic options
  • json2css -- Converts JSON to CSS pre-processor strings
  • json-content-demux -- Breaks up JSON defaults from content for easy templating


This acts as a glue layer for integration of spritesmith and json2css into grunt.

It expands the paths provided via minimatch, passes those on to spritesmith, processes the coordinates via json2css, and writes out the spritesheet and CSS variable declarations.


Spritesmith is where the magic happens. It was built with cross-platform functionality in mind and took a lot of TLC to get working just right.

It reads in the images via its engine, lays them out via layout, adds the sprites to a canvas, output the canvas, and callback with everything.

Aside: I was a few steps away from a cross-platform node-canvas. Hopefully, someone will implement that soon.

Another aside: I wanted to add URL based engine (canvas via an API) but could not find one. It's still on my TODO list to make one.


This was built for re-use and modular purification. It was made agnostic so that anything with a height and width dimension could be laid out in a specific algorithm.


This was built for simplified unit testing and re-use. It was built so that new templates could be easily added and tested.


This was built as an answer to a slick solution for encapsulating the relationship between template data and its template.

It initially came from toto and it has come up time and time again as a slick solution to this encapsulation. I have used it in jojo and want to use it as an elegant solution for keeping template interactivity self-contained.


This project was very fun to build and had a lot of thought put into it.

I hope you enjoy using it!

Related projects


Combine images into a spritesheet and CSS variables

Top articles

Lessons of a startup engineer

Lessons from being a 3x first engineer, former Uber engineer, and working at even more startups

Develop faster

Removing the tedium from creating, developing, and publishing repos.