spritify

SPRITIFY is a node.js package to create image sprite(s) from images and update css file(s) with new image sprite(s) details.

Features:

• Create image sprite(s), and search for background, background-image css properties in the css file, and update the value with the new sprite image url and dimension by adding/overwrite css properties like background-size, background-position, width ...etc.

• Option to optimize sprite css by comine class names to one background-image css property.

• Supports SVG sprites.

• Supports Retina sprites.

• Can inline sprites using base64 encoding.

• Can check for unused images in the sprite(s).

• Can check for missing images, by searching for image path in the background, background-image css properties and can't find the image.

• Can be used in grunt, gulp or any build tool.

Demo

Clone or download Spritify example repo and run it.

Install

npm install spritify --save-dev

OR

npm install -g spritify

CLI

Usage:
  spritify [OPTIONS] [ARGS]


Options:
  -h, --help : Help
  -v, --version : Version
  -c CONFIG, --config=CONFIG : JSON Config file path (It should be relative path)
  -s SRC, --src=SRC : Source directory of the images for the sprite image (It should be relative path).
  -d DEST, --dest=DEST : Destination file path of the sprite image (It should be relative path).
  -l LAYOUT, --layout=LAYOUT : layout of the sprite image e.g: 'top-down', 'left-right'.
  -p PADDING, --padding=PADDING : Padding pixels around the sprite image. e.g: 10.
  -svg, --svg : Flag to build svg sprite image

CLI usage example

./node_modules/.bin/spritify -c CONFIG/FILE/PATH.json

OR create only image sprite

./node_modules/.bin/spritify -s SOURCE/DIRECTORY/PATH/ -d DESTINATION/FILE/PATH.png -p 15 -l left-right

OR create only svg image sprite

./node_modules/.bin/spritify -s SOURCE/DIRECTORY/PATH/ -d DESTINATION/FILE/PATH.svg -svg

CLI config file schema example

{
    "css": [
        {
            "src": "__tests__/fixtures/css/style-a.css",
            "dest": "build/css/style-a.css"
        },
        {
            "optimize": false,
            "inline": true,
            "src": "__tests__/fixtures/css/style-inline.css",
            "dest": "build/css/style-inline.css"
        },
        {
            "optimize": false,
            "src": "__tests__/fixtures/css/style-svg-a.css",
            "dest": "build/css/style-svg-a.css"
        }
    ],
    "sprites": [
        {
            "layout": "top-down",
            "src": [
                "public/images/common",
                "public/images/other-icons"
            ],
            "dest": "build/img/sprite-site.png",
            "relative": "../img"
        },
        {
            "padding": 10,
            "layout": "top-down",
            "src": "__tests__/fixtures/img/icons",
            "dest": "build/images/sprite.png",
            "relative": "../images"
        },
        {
            "retina": 2,
            "src": "__tests__/fixtures/img/icons@2x",
            "dest": "build/images/[email protected]",
            "relative": "../images"
        },
        {
            "svg": true,
            "src": "__tests__/fixtures/img/svg",
            "dest": "build/images/sprite-svg.svg",
            "relative": "../images"
        }
    ]
}

Programatic usage

const Spritify = require('spritify');
Spritify.build(params, callback);

Programatic usage example

/* 
    File: ./bin/run-spritify.js
    Run: node ./bin/run-spritify.js
*/
const Spritify = require('spritify');

const params = {
    debug: true,
    showIgnoredRules: true,
    css: [
        {
            optimize: false,
            inline: true,
            src: 'public/stylesheets/site.css',
            dest: 'build/css/site.css'
        },
        {
            src: 'build/css/theme.css',
            dest: 'build/css/theme.css'
        }
    ],
    sprites: [
        {
            layout: 'top-down',
            src: [
                'public/images/common',
                'public/images/other-icons'
            ],
            dest: 'build/img/sprite-site.png',
            relative: '../img'
        },
        {
            layout: 'top-down',
            src: 'public/images/icons',
            dest: 'build/img/sprite.png',
            relative: '../img'
        },
        {
            padding: 15,
            retina: 2,
            layout: 'left-right',
            src: 'public/img/icons@2x',
            dest: 'build/img/[email protected]',
            relative: '../img'
        },
        {
            svg: true,
            src: 'public/img/svg',
            dest: 'build/img/svg-sprite.svg',
            relative: '../img'
        }
    ]
};

Spritify.build(params, (err) => {

    if (err) {
        console.error(err.stack || err);
        return;
    }
});

Spritify CSS Directives

| NAME | Syntax | Description | |----------|--------------------------|---------------------------------------------------------| | Ignore | /* spritify: ignore */ | Ignore statement, to ignore css rule or css declaration |

Documentation

Spritify.build(params, callback)

Generates sprite(s) based on the provided images, and search for background, background-image css properties in the css files based on the provided css, and it will update the value(s) with the new sprite image(s) and dimensions by adding/overwrite background-size, background-position, width ...etc.

params Object:

| NAME | TYPE | DEFAULT | REQUIRED | DESCRIPTION | |--------------------|----------------------|---------|----------|-----------------------------------| | css | Array of Objects | | YES | Array of spritify css object. | | sprites | Array of Objects | | YES | Array of spritify sprites object. | | debug | Boolean | false | NO | Option to show debug info. | | showIgnoredRules | Boolean | false | NO | Option to show ignored css rules. |

callback Function:

Is a callback function which should have signature function (err), err is Error|null.

css object:

| NAME | TYPE | DEFAULT | REQUIRED | DESCRIPTION | |-------------|---------------|---------|----------|---------------------------------------------------------------------------------------------| | src | String | | YES | Source path of the css file. | | dest | String | | YES | Destination path of the css file. | | optimize | Boolean | true | NO | Option to optimize sprite css by comine class names to one background-image css property. | | inline | Boolean | false | NO | Option inline sprites using base64 encoded. |

sprites object:

| NAME | TYPE | DEFAULT | REQUIRED | DESCRIPTION | |-------------|---------------------------------------|---------------|----------|---------------------------------------------------------------------------------------------| | src | String Or Array of Strings | | YES | Source directory path(s) of the images. | | dest | String | | YES | Destination path of the sprite file. | | relative | String | | YES | Relative destination directory path of the sprite in the css file. | | svg | Boolean | false | NO | Option to create svg sprite for svg images. | | padding | Number | 0 | NO | Option to add more padding around the images in the css. | | retina | Number | 1 | NO | Option to support retina images by setting value. e.g: to use 2X retina, set retina: 2. | | layout | String | binary-tree | NO | Option to pack images with. please layouts table. | | engine | String | pixelsmith | NO | Option to use different engine for spritesmith. |

Layouts

| top-down | left-right | diagonal | alt-diagonal | binary-tree | |---------------------------|-------------------------------|---------------------------|-----------------------------------|---------------------------------| | | | | | |

License

Copyright 2017, Yahoo Holdings.

Copyrights licensed under the New BSD License. See the accompanying LICENSE file for terms.