jkphl/node-iconizr

SVG + PNG icon kit generator — A low-level Node.js module that creates a CSS icon kit from a bunch of SVG files, serving them as SVG / PNG sprites or embedded data URIs along with suitable CSS / Sass / LESS / Stylus etc. stylesheet resources and a JavaScript loader for easy integration into your HTML documents

ATTENTION: Not yet based on the latest svg-sprite generation!

This version of node-iconizr is still based on an outdated version of svg-sprite. Links to the svg-sprite manual have been adapted. An updated version of node-iconizr will be available soon, supporting all the shiny new features. Thanks for your patience! <3

iconizr

> Node.js version

iconizr is a Node.js module that reads a folder of SVG images and creates a CSS icon kit out of them, including:

• cleaned versions of the original SVG icons (optional),
• a single compact SVG icon sprite,
• optimized single PNG icons (optional),
• an optimized combined PNG icon sprite,
• corresponding CSS stylesheets in customizable formats (e.g. CSS, Sass, LESS, Stylus etc.),
• an HTML fragment including some JavaScript for asynchronously loading the most appropriate stylesheet flavour (depending on the client)
• and a couple of HTML preview documents (depending on the options you specified) for previewing and testing the different stylesheets (optional).

The stylesheets are rendered using Mustache templates, so you can control which output formats are generated (and how they are structured). For each of them, a set of several stylesheets are created, differing in the way the icons are served to clients:

• SVG single image icons (optional),
• SVG data URIs,
• SVG sprite references,
• PNG single image icons (optional),
• PNG data URIs and
• PNG sprite references.

Installation & usage

To install iconizr, run

npm install iconizr -g

on the command line.

Usage

The iconizr module exposes only one method, createIconKit(). Use it like this:

var Iconizr			    = require('iconizr'),
options				    = {
	
	// svg-sprite inferred options
	render				: {
		css				: false,
		scss			: 'sass/output/directory/',
		less			: {
			template	: 'path/to/less/mustache/template.less',
			dest		: '/absolute/path/to/dest/file'
		}
	},
	// ...
	
	// iconizr specific options
	quantize			: true,
	level				: 5
	/* Further configuration options, see below ... */
},
callback				= function(err, results) { /*
	If no error occurs, `results` will be a JSON object like this one:
	
	{
	   success			: true,		// Overall success
	   length			: 3,		// Total number of files written
	   files			: {			// Files along with their file size in bytes
	      '/path/to/your/cwd/css/output/directory/svg/sprite.svg'	: 436823,
	      '/path/to/your/cwd/css/output/directory/sprite.css'		: 1821,
	      '/path/to/your/cwd/sass/output/directory/_sprite.scss'	: 2197
	   },
	   options          : {         // refined configuration options, see above 
           // ...
	   },
	   data             : {         // Mustache template variables, see below
	       // ...
	   }
	}
	
*/};
Iconizr.createIconKit('path/with/svg/images', 'css/output/directory', options, callback);

The createIconKit() method will refuse to run if you don't pass exactly four arguments:

1. A path to be used as the input directory containing the SVG images for sprite creation. A relative path refers to the current working directory.
2. A main / default output directory, used for creating the stylesheet resources (CSS / Sass / LESS / Stylus etc. if activated and not specified otherwise; see the svg-sprite rendering options) and serving as a base for the sprite subdirectory given by spritedir see (svg-sprite configuration options). A relative path refers to the current working directory.
3. An object with configuration options (for both svg-sprite and iconizr specific). None of these options is mandatory, so you may pass an empty object {} here.
4. A callback to be run when the sprite creation has finished (with or without error).

Configuration

Options inferred from svg-sprite

iconizr is built on top of svg-sprite, which is a Node.js module for SVG sprite generation. All of svg-sprite's configuration options apply for iconizr as well. For a complete reference please see the svg-sprite documentation.

Option	Description
render	Rendering configuration (output formats like CSS, Sass, LESS, Stylus, HTML with inline SVG, etc.)
variables	Custom Mustache rendering variables [{}]
spritedir	Sprite subdirectory name ["svg"]
sprite	Sprite file name ["sprite"]
prefix	CSS selector prefix ["svg"]
common	Common CSS selector for all images [empty]
maxwidth	Maximum single image width [1000]
maxheight	Maximum single image height [1000]
padding	Transparent padding around the single images (in pixel) [0]
layout	Image arrangement within the sprite ("vertical", "horizontal" or "diagonal") ["vertical"]
pseudo	Character sequence for denoting CSS pseudo classes ["~"]
dims	Render image dimensions as separate CSS rules [false]
keep	Keep intermediate SVG files (inside the sprite subdirectory) [false]
recursive	Recursive scan of the input directory for SVG files [false]
verbose	Output verbose progress information (0-3) [0]
cleanwith	Module to be used for SVG cleaning. Currently "scour" or "svgo" ["svgo"]
cleanconfig	Configuration options for the cleaning module [{}]

In particular, iconizr's rendering configuration and output format behaviour is identical to svg-sprite, so please have a look there for further reference.

Options for iconizr

Property	Type	Description
quantize	Boolean	Whether to quantize PNG images (reduce to 8-bit depth) using pngquant. The quantized images are only used if they are smaller in file size than their the originals (and this is not necessarily the case for all PNG files). Quantization may also impact the visual image quality, so please make sure to compare the result to the original images. Defaults to false.
level	Number (0-11)	This is the optimization level for PNG files. It has to lie between 0 and 11 (inclusive) and defaults to 4, with 0 meaning "no optimization", 1 meaning "fast & rough" and 11 meaning "slow & high quality". Setting this to a high value may result in a very long processing time. Defaults to 3.
embed	String	If given, iconizr will use this value as path prefix to embed the stylesheets into your HTML documents (used for the JavaScript loader fragment). By default, the path segment between the current working directory and the main output directory will be used as a root-relative embed path (i.e. giving path/to/css as output directory will result in the loader fragment expecting the CSS stylesheets to lie at /path/to/css/<stylesheet-flavour>.css). You may specify a period . here to make the embed path relative to your HTML document (i.e. ./<stylesheet-flavour>.css), or use any other relative path (e.g. ../resources for the embed path ../resources/<stylesheet-flavour>.css).
svg	Number	This is the maximum length a SVG data URI may have. If only one icon exceeds this threshold, all data URIs of this icon set will be changed to external SVG sprite references. Defaults to 1048576 (1MB), minimum is 1024 (1kB).
png	Number	This is the maximum length a PNG data URI may have. If only one icon exceeds this threshold, all data URIs of this icon set will be changed to external PNG sprite references. Defaults to 32768 (32KB = Internet Explorer 8 limit), minimum is 1024 (1kB).
preview	String	If given and not empty, a set of preview HTML documents will be rendered that can be used for previewing and testing the icon kit. The given value will be used as directory path relative to the main output directory, whereas the main preview document will be named after your CSS file name ({render: {css: '...'}}) or the prefix option (in case no CSS files are generated).
loader	Object	With this option you get some control about the format and destination of the JavaScript loader fragment: loader.type may be "html" (for an HTML loader fragment; this is the default) or "js" (for a JavaScript file only). The Boolean loader.minify controls whether the loader script will get uglyfied (defaults to TRUE). Finally, loader.dest is the path (relative to the main output directory) where the loader resource will be written to (defaulting to ".").

Custom output formats & inline SVG embedding

The output rendering of iconizr is based on Mustache templates, which enables full customization of the generated results. You can even introduce completely new output formats. For details please see the svg-sprite documentation.

Also, you may use iconizr to create an inline SVG sprite that can be embedded directly into your HTML documents. Please see the svg-sprite documentation for details.

Other versions

Besides this Node.js module there are several different versions of iconizr:

• A Grunt plugin wrapping around this module.
• A PHP command line version (that in fact is the "original" one, but compared to the Node.js / Grunt branch it's a little outdated at the moment ...).
• The online service at iconizr.com that's based on the aforementioned PHP version (you can use it for creating CSS icon kits without the need of a local installation).
• Finally, Haithem Bel Haj published a Grunt plugin that's also based on the PHP version. I never tried this one myself, though.

Release History

v0.2.3

• Added concurrent task limit (#11)
• Updated dependencies (#9)
• Added support for JS-only loader fragment (#10)

v0.2.2

• Added a Stylus output template (#5)
• Added the variables config option (grunt-iconizr #13)

v0.2.1

• Fixed invalid background-position style in Sass / LESS templates (#4)

v0.2.0

• Switched to mustache.js for extended function support
• Fixed full disabling of output rendering (#2)
• Don't crash with empty input directory (#3)
• Fixed bug with the SVG sprite not used by the Sass & LESS output types (grunt-iconizr issue #6)
• Added new HTML output format for rendering an inline SVG HTML implementation (#1)
• Added new SVG output format for rendering an inline SVG sprite (#1)
• Documentation corrections

v0.1.0

• Initial release

Contributors

• Ralf Hortt

Legal

Copyright © 2014 Joschi Kuphal [email protected] / @jkphl

iconizr is licensed under the terms of the MIT license.

The contained example SVG icons are part of the Tango Icon Library and belong to the Public Domain.

node-iconizr's Issues

"Max buffer exceeded" when creating PNG fallbacks with PhantomJS

In case the sprite dimensions are too big, it's possible that the max. buffer for the PhantomJS call gets exceeded. There should be a third argument to the execFile() command:

execFile(phantomjs, [ /* ... */ ], {maxBuffer: maxBufferSize}, callback);

Detect and collate redundant shape usages in the sprite

There are situations where one particular SVG shape needs to be present multiple times in the sprite, e.g. when you have a particular icon and several different hover states for it. Right now, you need to have several copies of the shape, each with its individual hover state. It would be nice if iconizr could detect these redundant icons (e.g. by file hashes) and put <use> elements for the shape copies in the sprite instead (would save some size).

Use it as command line

It would be useful to have it as command line. Just like the PHP Cli one.

Binary file permissions after installation

Under certain circumstances, the following binaries have to be chmodded / paxctld after their installation:

• node_modules/pngcrush-bin/vendor/pngcrush
• node_modules/pngquant-bin/vendor/pngquant
• node_modules/optipng-bin/vendor/optipng

Using relative dimensions

Hi, thanks for iconizr!

I'm not a developer but would like to use your service. Since I read about SVG - sprites in particular - I'm really interested in creating an icon set based on a SVG-sprite. These are the ressources I read:

• http://css-tricks.com/svg-sprites-use-better-icon-fonts/
• http://css-tricks.com/svg-symbol-good-choice-icons/
• http://www.smashingmagazine.com/2012/01/16/resolution-independence-with-svg/ (that's great!)

I tried many variations but didn't get a satisfying solution (maybe because I'm not a developer). After finding iconizr I thought that would be my personal solution but then I realized that I can't resize the icons with CSS - at least very complicated. Plus: the generated SVG-sprite is very huge (~450KB) which contains pixel dimensions - not em. I think that's the key-issue.

I think iconizr would be a great tool for designer like me :)

PS: You can see my icons here: http://goo.gl/AEHVOB
PPS: My first posting here on Github, maybe that's not the way is is supposed to be to start a discussion about that functionality - sorry!

getimo

Different size icons not being handled correctly

I tried generating a sprite sheet with a set of icons that have different sizes. This worked correctly on the online version of iconizr (they all get scaled down to the specified size).
In the node version the generated spritesheet was messed up in different ways:

• The large ones scaled to the size defined.
• The small ones scaled with a similar factor as the large ones rendering them really small.
• The offsets generated in the sprite sheet and the less/css were inconsistent. For 32px there was offsets of 8px or even odd numbers like 17px.
• Possibly as a side effect of the issues above the png sprite sheet generated all blank (but it has the correct size).

Is there a way to handle different sizes or is this a limitation?

pngcrush-bin dependency outdated

The pngcrush-bin dependency in package.json is outdated.
npm module node-grunt is also affected as it got npm module (node-)iconizr as depenceny.

The outdated pngcrush-bin expects a specific GLIBC library which is not present on many systems and fail, also the build source url is incorrect.

[...]
Creating PNG versions of 2 SVG images (including the sprite) ...
{ [Error: Command failed: [...]/node_modules/iconizr/node_modules/pngcrush-bin/vendor/pngcrush: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.14' not found (required by [...]/node_modules/iconizr/node_modules/pngcrush-bin/vendor/pngcrush)] killed: false, code: 1, signal: null }

Done, without errors.
[...]

Although no error was indicated in the end of the task, only one PNG was generated, the others missing and the style files weren't written.

This can be solved however by forcing iconizr to use the latest stable pngcrush-bin dependency:

(cwd is project dir)
$ rm -r ./node_modules/iconizr/node_modules/pngcrush-bin/
$ npm install pngcrush-bin

Creating PNG versions of 2 SVG images (including the sprite) ...
{ [Error: Command failed: ] killed: false, code: 1, signal: null }

The pngcrush-bin pngcrush command would work again, the PNGs are created -
however, there still seems to be at least some misinterpretation of its exit code as the command is remarked as 'failed' during iconizr run and the subsequent css/sass/stylus/... files aren't written.

So bumping the pngcrush-bin dependency to latest stable + adjusting its invocation in iconizr will solve this issue.

Thank you in advance.
With best regards.

Disabling stylesheet output altogether doesn't work

The configuration

{
    render: {
        css: false
    }
}

should suppress CSS output rendering altogether. As long as no Sass / LESS / whatever rendering is enabled, only the SVG and PNG sprites should be generated. As reported by @benfrain, this doesn't work at the moment. There will always be CSS files being generated.

Invalid `background-position` in included Sass / LESS templates

The included Sass and LESS templates render an invalid background-position style into the dataURI stylesheets (both SVG and PNG), although this is not needed in these cases.

Add support for inline SVG

In his article about SVG use with External Source, @chriscoyier shows a nice way to use an external SVG file for inlined usage. Iconizr should support this variant. Most likely this is also related to what @lukasoppermann referred to as "HTML implementation" in this grunt-svg-sprite issue.

Crashes with empty input directory

If the input directory doesn't contain any SVG files, the process crashes.

npm install iconizr [-g] fails every time

I can't install this via npm at all, either locally or -globally. Ideally I'd like to use it from the CL as mentioned in #7.