node.js sprites generator for LESS

Requirements

less-sprites uses ImageMagick, so install it first.

Installation

npm install less-sprites

Usage

Write a list of source images into a .json file: { "files": ["icon1.png", "icon2.png"] }

Create the sprite:

less-sprites my-sprite.json

There are more options you can specify:

{
	// Direction of image placement, default "bottom"
	"direction": "right|bottom",
	// Directory relative to the .json file where source files are located, default "."
	"dir": ".",
	// Basename of the final sprite, default is same as the name of the .json file.
	"sprite": "icons-sprite.png",
	// List of source images (without directory, in PNG).
	"files": ["icon1.png", "icon2.png"]
}

Using the sprite in your LESS stylesheet

less-sprites my-sprite.json creates two files:

• my-sprite.png - the final sprite image
• my-sprite.less - positions of the images inside the sprite

In your stylesheet you target the original image, not the sprite; it will be translated during compilation.

CSS without less-sprites

.icon-first {
	background: url('/img/icon1.png');
}
.icon-second {
	background: url('img/icon2.png');
}

LESS with less-sprites

@import "icons/icons-sprite.less"

.icon-first {
	.sprite('/img/icon1.png');
}
.icon-second {
	.sprite('img/icon2.png');
}

which is later compiled into final CSS:

.icon-first {
	background: url("/img/icons-sprite.png") 0px 0px;
}
.icon-second {
	background: url("img/icons-sprite.png") 0px -20px;
}

Now when you need to add a new image to the sprite, you simply it to the .json file and call less-sprites. No extra work is needed in your stylesheets.

Name conflicts

If you @import several sprites into global namespace there is a possibility of name conflict (imagine referencing two images from two different places as ../image.png). The best way to avoid this is to always import inside a scope:

.my-icons {
	@import "...";
	.icon-first {
		.sprite('...');
	}
}

Alternatively you can provide extra parameter to the .sprite() mixin with the name of the sprite. So if you have folder icons/ with the sprite icons/my-sprite.png, then you can:

@import "icons/my-sprite.less";
.icon-first {
	.sprite('my-sprite', 'img/icon1.png');
}

License

The MIT License.