Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

spritezero

mapbox137ISCdeprecated3.8.0

This module is now under the @mapbox namespace: install @mapbox/spritezero instead

small opinionated sprites

sprite, images, icons, json

readme

npm version build status

spritezero

Small opinionated sprites.

Why is this different than sprite generation libraries like spritesmith? spritezero was initially created to power a sprite API, and thus is geared towards performance, as well as an ability to work with image data in buffers rather than on disk. Also, since version 2.0, spritezero generates sprites based on SVG graphics alone, therefore making it possible to support @2x and higher-dpi sprites from the same source.

Usage

var spritezero = require('spritezero');
var fs = require('fs');
var glob = require('glob');
var path = require('path');

[1, 2, 4].forEach(function(pxRatio) {
    var svgs = glob.sync(path.resolve(path.join(__dirname, 'input/*.svg')))
        .map(function(f) {
            return {
                svg: fs.readFileSync(f),
                id: path.basename(f).replace('.svg', '')
            };
        });
    var pngPath = path.resolve(path.join(__dirname, 'output/sprite@' + pxRatio + '.png'));
    var jsonPath = path.resolve(path.join(__dirname, 'output/sprite@' + pxRatio + '.json'));

    // Pass `true` in the layout parameter to generate a data layout
    // suitable for exporting to a JSON sprite manifest file.
    spritezero.generateLayout(svgs, pxRatio, true, function(err, dataLayout) {
        if (err) return;
        fs.writeFileSync(jsonPath, JSON.stringify(dataLayout)));
    });

    // Pass `false` in the layout parameter to generate an image layout
    // suitable for exporting to a PNG sprite image file.
    spritezero.generateLayout(svgs, pxRatio, false, function(err, imageLayout) {
        spritezero.generateImage(imageLayout, function(err, image) {
            if (err) return;
            fs.writeFileSync(pngPath, image);
        });
    });

});

Documentation

Complete API documentation is here: http://mapbox.github.io/spritezero/

Installation

Requires nodejs v4.0.0 or greater.

$ npm install spritezero

Executable

spritezero-cli is an executable for bundling and creating your own sprites from a folder of svg's:

$ npm install -g spritezero-cli
$ spritezero --help

Usage:
spritezero [output filename] [input directory]
  --retina      shorthand for --ratio=2
  --ratio=[n]   pixel ratio

changelog

:warning: = breaking change

3.8.0

2016-09-15
  • Update to mapnik 3.5.14 (#26)

3.7.1

2016-09-14
  • Pin mapnik dependency at version 3.5.13 (#33)

3.7.0

2016-08-10
  • Update to shelf-pack v2
  • ShelfPack now trims sprite to minimum dimensions after a batch pack
  • Make sure heightAscThanNameComparator is transitive (#29)

3.6.0

2016-06-05
  • Perf improvement, replace sort-by with custom comparator (#27)
  • Add generateLayoutUnique function - map identical images to multiple names (#25)

3.5.0

2016-03-30
  • Use shelf-pack binpacker (#22)

3.4.0

2016-03-08
  • Sort icons array to produce a more deterministic sprite sheet (#24)

3.3.0

2016-02-27
  • Updated to mapnik 3.5.0

3.2.2

2016-02-03
  • Add missing var (#20)

3.2.1

2016-01-19
  • Remove bin in package.json

3.2.0

2016-01-19
  • :warning: Remove cli, point to spritezero-cli (#19)

3.1.0

2016-01-13
  • Add executeable and documentation

3.0.2

2016-01-09
  • Update dependencies
  • Update fixtures and tests

3.0.1

2015-10-10
  • Update dependencies

3.0.0

2015-09-03
  • :warning: Changes the generateLayout function to be asynchronous (#14)

2.1.0

2015-08-13
  • No longer throws an error if generateImage() is supplied with empty list (#13)

2.0.0

2015-08-05
  • :warning: In the second major version, spritezero makes a big pivot: instead of positioning and compositing raster sprites, it receives and composites vector sprites composed of SVG data.