CoffeeScript/JavaScript stylesheet-based sprite image engine.

Coffee Sprites

CoffeeSprites is a plugin for Node.js CoffeeStylesheets which allows you to use functions like sprite_position(), sprite_height(), image_width(), sprite_map(), etc. within your * markup to automatically fetch images and generate css sprites at render time.

If you come from the Ruby on Rails community, you will immediately recognize conventions from Spriting with Compass/SASS, originally Lemonade.

sudo apt-get install libgd2-xpm-dev # on ubuntu; a libgd dependency
npm install coffee-sprites
CoffeeStylesheets = require 'coffee-stylesheets'
engine = new CoffeeStylesheets format: true
CoffeeSprites = require __dirname + 'coffee-sprites'
engine.use new CoffeeSprites
  image_path: __dirname + '/precompile/assets/sprites/'
  sprite_path: __dirname + '/static/public/assets/'
  sprite_url:  'assets/'
  stylesheet = ->
    body ->
      background '#eee'
      color '#333'
      margin '20px'
    wigi = sprite_map 'wigi',
      spacing: 10
    s '#wigi'->
      background "url(#{sprite_url wigi}) no-repeat"
      height sprite_height wigi'fly-3'
      width sprite_width wigi'fly-3'
    for iof 'walk-1 walk-2 walk-3 run-1 run-2 run-3 fly-1 fly-2 fly-3 fall jump'.split ' '
      s '#wigi.wigi-'+i->
        background_position sprite_position wigiv
css = engine.render stylesheet(err, css) ->
  fs.writeFileSync __dirname + '/static/public/assets/application.css'css

Will output CSS like this:

#wigi {
  background: url(./wigi-2e192be7fd.png) no-repeat;
  height: 112px;
  width: 96px;
#wigi.wigi-0 {
  background-position: 0 -122px;
#wigi.wigi-1 {
  background-position: 0 -244px;
#wigi.wigi-2 {
  background-position: 0 -366px;
#wigi.wigi-3 {
  background-position: 0 -484px;
#wigi.wigi-4 {
  background-position: 0 -606px;
#wigi.wigi-5 {
  background-position: 0 -728px;
#wigi.wigi-6 {
  background-position: 0 -850px;
#wigi.wigi-7 {
  background-position: 0 -968px;
#wigi.wigi-8 {
  background-position: 0 0;
#wigi.wigi-9 {
  background-position: 0 -1086px;
#wigi.wigi-10 {
  background-position: 0 -1208px;

And the sprite image(s) will turn out like this:

For the very latest and most comprehensive example, see test/fixtures/precompile/assets/stylesheets/

npm test # build coffee, run mocha unit test, run chrome browser integration test
  • sprites that repeat-x and repeat-y are left to be implemented (coming soon!)
  • add validation to ensure no function can be called with invalid input to avoid semi-cryptic errors
  • could probably simplify by calculating x, y, width, height using gd directly and once during render() rather than as-we-go