nodejs-sprite-gen

A fast, modern CLI tool for generating image sprites and CSS stylesheets. Combine multiple images into a single optimized sprite sheet to reduce HTTP requests and improve page load times.

Features

• 🚀 Fast image processing with Sharp
• 📦 Supports multiple input formats (JPG, PNG, WebP, GIF, BMP)
• 🎨 Generates clean CSS, SCSS, or LESS stylesheets
• 📐 Resize images on-the-fly
• 🔄 Grid, horizontal or vertical layouts
• ⚙️ Configurable padding between images
• 🌟 Zero configuration defaults
• 💻 Can be used as CLI or programmatically

Installation

# Global installation
npm install -g nodejs-sprite-gen

# Or use with npx (no installation needed)
npx nodejs-sprite-gen --input ./images

# Local installation for project
npm install --save-dev nodejs-sprite-gen

Usage

Basic Usage

nodejs-sprite-gen --input ./images

This will:

• Read all images from ./images directory
• Generate sprite.png and sprite.css in ./sprites directory

Advanced Usage

nodejs-sprite-gen \
  --input ./flags \
  --output ./dist/sprites \
  --name country-flags \
  --size 25x25 \
  --layout horizontal \
  --padding 10 \
  --css-format scss \
  --prefix some_name_for_css_classes

Options

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --input <path> | -i | Input directory containing images (required) | - | | --output <path> | -o | Output directory | ./sprites | | --name <name> | -n | Output filename (without extension) | sprite | | --layout <type> | -l | Layout: horizontal or vertical | vertical | | --padding <pixels> | -p | Padding between images | 0 | | --size <WxH> | -s | Resize images (e.g., 25x25) | original size | | --css-format <format> | - | CSS format: css, scss, or less | css | | --prefix | - | The CSS class name prefix | sprite | | --no-css | - | Skip CSS generation | generates CSS |

Using in npm scripts

Add to your package.json:

{
  "scripts": {
    "build:sprites": "nodejs-sprite-gen --input ./assets/icons --size 32x32"
  }
}

Run with:

npm run build:sprites

Programmatic Usage

You can also use nodejs-sprite-gen programmatically in your Node.js projects:

const { generateSprite } = require('nodejs-sprite-gen');

async function buildSprites() {
  const result = await generateSprite({
    inputDir: './images',
    outputDir: './sprites',
    spriteName: 'sprite',
    layout: 'vertical',
    padding: 0,
    resize: { width: 25, height: 25 }, // optional
    generateCSS: true,
    cssFormat: 'css',
    prefix: 'icon'
  });

  console.log(`Generated: ${result.imagePath}`);
  console.log(`CSS: ${result.cssPath}`);
  console.log(`Images: ${result.imageCount}`);
}

buildSprites();

Output

Generated PNG Sprite

A single optimized PNG file with transparency, containing all your images.

Generated CSS

.sprite {
  display: inline-block;
  background-image: url('sprite.png');
  background-repeat: no-repeat;
}

.sprite-icon-home {
  width: 32px;
  height: 32px;
  background-position: -0px -0px;
}

.sprite-icon-settings {
  width: 32px;
  height: 32px;
  background-position: -0px -32px;
}

Using the Sprite in HTML

<div class="sprite sprite-icon-home"></div>
<div class="sprite sprite-icon-settings"></div>

Examples

Icon Sprites

nodejs-sprite-gen --input ./icons --size 32x32 --padding 2

Flag Sprites

nodejs-sprite-gen --input ./temp_images --output ./out --size 250x100 --prefix icon --layout grid

SCSS Output

nodejs-sprite-gen --input ./images --css-format scss

Requirements

• Node.js >= 16.0.0

License

MIT

Author

Gidon Handler [email protected]

Made with ❤️ for better web performance