vite-plugin-spritesmith2

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

Install

# use yarn (recommend)
yarn add -D vite-plugin-spritesmith2
# or use npm
npm install --save-dev vite-plugin-spritesmith2

Example

Let's say you have the following folder structure

/
|-src
| |-assets
| | |-sprites
| | | |-new.png
| | | |-open.png
| | | |-save.png
| | ...
| |-scss.handlebars
| ...
|-vite.config.js

Then you need to instantiate the plugin in the vite config like this:

import { defineConfig } from 'vite';
import Spritesmith from 'vite-plugin-spritesmith2';
export default defineConfig({
  plugins: [
    Spritesmith({
      watch: true,
      src: {
        cwd: './src/assets/sprites',
        glob: '*.png',
      },
      target: {
        image: './src/sprite/img/sprite.png',
        css: [
          [
            './src/sprite/style/sprite.scss',
            {
              format: 'handlebars_based_template',
            },
          ],
        ],
      },
      apiOptions: {
        cssImageRef: 'assets/target/sprite.png',
        spritesheet_info: {
          name: 'vite1',
          format: 'handlebars_based_template',
        },
      },
      customTemplates: {
        handlebars_based_template: './src/sprite/scss.handlebars',
      },
    }),
  ],
});

And then just use it

@import './assets/sprite/style/sprite.scss';
.icon {
  @include sprites($spritesheet-sprites);
}

So the way generated image is accessed from the generated API now must be specified manually.

Config

• watch - should watch source images change or not, default false

• src - used to build a list of source images

  • cwd should be the closest common directory for all source images;
  • glob path pattern of source images

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

• target - generated files

  • image - the target image's filename.

  • css - can be one of the following

    • "full/path/to/spritesheet/api" - for example path.resolve(__dirname, 'src/spritesmith-generated/sprite.styl')

    • ["full/path/to/spritesheet/api1", "full/path/to/spritesheet/api2"],

    • ["full/path/to/spritesheet/api1", ["full/path/to/spritesheet/api2", spritesmithTemplatesOptions]] spritesmithTemplatesOptions - is the second argument here

      for example

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

• apiOptions - optional

  • generateSpriteName - a function. Takes a full path to a 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)
  • spritesheet_name, retina_spritesheet_name - passed to spritesheet-templates (retina_spritesheet_name only takes effect if apiOptions.retina is also specified)
  • cssImageRef - a path by which a generated image will be referenced in API. If target.image is interpolated, cssImageRef should be interpolated the same way too.
  • handlebarsHelpers - an 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
    • Note that handlebarsHelpers is global. If you have multiple instances of SpritesmithPlugin, helpers defined later will override helpers defined earlier.

• spritesmithOptions - optional. Options for spritesmith

• retina - optional, when specified, uses retina capabilities of spritesheet-templates. Can be either a suffix string (like '@2x') or an 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. May take one of the two values: 'retina' and 'normal'
            normalName: String, //a full path to the corresponding normal source image
            retinaName: String, //a full path to the corresponding retina source image
        }

  • targetImage - a full path to the generated retina image

  • cssImageRef - a path by which generated image will be referenced in the API

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

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

• customTemplates - optional. An object with keys and values corresponding to format names and template descriptions respectively. Template description can be either a path/to/handlebars/template/file or a template function

  You can use templates registered here as format in "target.css"

  For example you can write something like this

  var templateFunction = function (data) {
    var shared = '.ico { background-image: url(I) }'.replace(
      'I',
      data.sprites[0].image
    );

    var perSprite = data.sprites
      .map(function (sprite) {
        return '.ico-N { width: Wpx; height: Hpx; background-position: Xpx Ypx; }'
          .replace('N', sprite.name)
          .replace('W', sprite.width)
          .replace('H', sprite.height)
          .replace('X', sprite.offset_x)
          .replace('Y', sprite.offset_y);
      })
      .join('\n');

    return shared + '\n' + perSprite;
  };

module.exports = {
    ...
    plugins: [
        new SpritesmithPlugin({
            target: {
                ...
                css: [
                    [path.resolve(__dirname, 'src/spritesmith-generated/sprite-1.css'), {
                        format: 'function_based_template'
                    }],
                    [path.resolve(__dirname, 'src/spritesmith-generated/sprite-2.css'), {
                        format: 'handlebars_based_template'
                    }]
                ]
            },
            customTemplates: {
                'function_based_template': templateFunction,
                'handlebars_based_template': path.resolve(__dirname, '../my_handlebars_template.handlebars')
            },
            ...
        })
    ]
}

License

MIT