Webpack plugin that converts set of images into a spritesheet and SASS/LESS/Stylus mixins, using spritesmith and spritesheet-templates

All ideas are shamelessly taken from gulp.spritesmith.

Example

Let's say you have following folder structure

/
|-src
| |-ico
| | |-new.png
| | |-open.png
| | |-save.png
| | ...
| |-style.styl
| ...
|-webpack.config.js

Then you need to instantiate plugin in webpack config like this:

//webpack.config.js
var path = require('path');

var SpritesmithPlugin = require('webpack-spritesmith');

module.exports = {
    // ...
    module: {
        loaders: [
            {test: /\.styl$/, loaders: [
                'style',
                'css',
                'stylus'
            ]},
            {test: /\.png$/, loaders: [
                'file?name=i/[hash].[ext]'
            ]}
        ]
    },
    resolve: {
        modulesDirectories: ["web_modules", "node_modules", "spritesmith-generated"]
    },
    plugins: [
        new SpritesmithPlugin({
            src: {
                cwd: path.resolve(__dirname, 'src/ico'),
                glob: '*.png'
            },
            target: {
                image: path.resolve(__dirname, 'src/spritesmith-generated/sprite.png'),
                css: path.resolve(__dirname, 'src/spritesmith-generated/sprite.styl')
            },
            apiOptions: {
                cssImageRef: "~sprite.png"
            }
        })
    ]
    // ...
};

And then just use it

//style.styl
@import '~sprite.styl'

.close-button
    sprite($close)
.open-button
    sprite($open)

There are few things to notice in config

• file-loader used for generated image
• resolve contains location of where generated image is
• cssImageRef is specified as '~sprite.png'

So the way generated image is accessed from generated API at the moment has to be specified manually.

Config

• src - used to build list of source images

  • cwd should be the closest common directory for all source images;
  • glob well... it is a glob

  cwd and glob both will be passed directly to glob (and gaze in watch mode), then results will be used as list of source images

• target - generated files

  • image - target image filename
  • css - can be string or array of strings and options for spritesheet-templates
    • String : target spritesheet filename, can be css, stylus, less, sass or json file
    • Array : used if you want to specify multiple css targets and/or options for spritesheet-templates. Each element must be either string with path to target file or Array with that string and object with options

       ...
       css: [
           path.resolve(__dirname, 'src/spritesmith-generated/sprite.styl'),
           [path.resolve(__dirname, 'src/spritesmith-generated/sprite.json'), {
               format: 'json_texture'
           }]
       ]

• apiOptions - optional

  • generateSpriteName - function. Takes full path to source image file and expected to return name by which it will be referenced in API. Return value will be used as sprite.name for spritesheet-templates. Default behaviour is to use filename (without dirname and extension)
  • cssImageRef - path by which generated image will be referenced in API

• spritesmithOptions - optional. Options for spritesmith

• retina - optional, when specified, uses retina capabilities of spritesheet-templates. Can be either suffix string (like '@2x') or object consisting of three fields:

  • classifier - Function that allows to say which source is for retina spritesheet and which is not. Will be called with full path to source file, and should return an object of this format -

        {
            type: String, // determines which kind of source is this. Can contain one of two values: 'retina' and 'normal'
            normalName: String, //full path to corresponding normal source image
            retinaName: String, //full path to corresponding retina source image
        }

  • targetImage - full path to generated retina image
  • cssImageRef - path by which generated image will be referenced in API

  When used as suffix string it applies to source files, filename for retina spritesheet image and cssImageRef

  apiOptions.generateSpriteName will be applied to normalName returned by retina.classifier

How it works

Plugin eats list of images in form of glob (config.src.cwd, config.src.glob), and spits out two files: spritesheet (config.target.image) and some API (config.target.css) in format that spritesheet-templates can produce. These files are expected to be used as source files in your project.

Basically plugin simply wires together webpack, spritesmith and spritesheet-templates. The only piece of logic it does by itself is determining which format to use judging by file extensions in config.target.css.

Breaking changes in 0.2.0

There is no spritesheetTemplatesOptions anymore, since there can be multiple target.css, it moved there.

//was
{
  target: {
    ...
    css: path.resolve(__dirname, 'src/spritesmith-generated/sprite.json'),
  },
  spritesheetTemplatesOptions: {format: 'json_texture'}
}
//now
{
  target: {
    ...
    css: [
      [path.resolve(__dirname, 'src/spritesmith-generated/sprite.json'), {
        format: 'json_texture'
      }],
      [path.resolve(__dirname, 'src/spritesmith-generated/sprite-2.json'), {
        format: 'json_array'
      }]
    ]
  }
}