# spritesmith

> Utility that takes images and creates a spritesheet with JSON sprite data

Latest version **3.5.1** (published 2024-10-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install spritesmith
pnpm add spritesmith
yarn add spritesmith
bun add spritesmith
```

## Health

**Score 33/100 (F)** — status: maintenance-mode.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.5.1 |
| Published | 2024-10-23 |
| First published | 2012-11-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/spritesmith) |
| Module format | CommonJS |
| Node | >= 4.0.0 |
| Dependencies | 5 |
| Unpacked size | 87.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 927 |
| Author | Todd Wolfson |
| Maintainers | twolfson |
| Keywords | sprite, spritesheet, css |

## Links

- npm: https://www.npmjs.com/package/spritesmith
- Repository: https://github.com/twolfson/spritesmith
- Issues: https://github.com/twolfson/spritesmith/issues
- npm.io page: https://npm.io/package/spritesmith

## Dependencies (5)

- [layout](https://npm.io/package/layout.md) ~2.2.0
- [semver](https://npm.io/package/semver.md) ~5.7.2
- [through2](https://npm.io/package/through2.md) ~2.0.0
- [pixelsmith](https://npm.io/package/pixelsmith.md) ^2.3.0
- [concat-stream](https://npm.io/package/concat-stream.md) ~1.5.1

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 3.5.1 (latest) — 2024-10-23
- 3.5.0 — 2024-10-23
- 3.4.1 — 2023-01-28
- 3.4.0 — 2019-09-13
- 3.3.1 — 2018-05-31
- 3.3.0 — 2018-01-06
- 3.2.1 — 2017-11-10
- 3.2.0 — 2017-11-10
- 3.1.1 — 2017-04-12
- 3.1.0 — 2016-01-29
- 3.0.1 — 2016-01-11
- 3.0.0 — 2015-11-22
- 2.0.1 — 2015-11-18
- 2.0.0 — 2015-11-18
- 1.5.0 — 2015-11-12
- … 61 more at https://npm.io/package/spritesmith/versions

## README

# spritesmith [![Build status](https://travis-ci.org/twolfson/spritesmith.png?branch=master)](https://travis-ci.org/twolfson/spritesmith) [![Subscribe to newsletter](https://img.shields.io/badge/newsletter-subscribe-blue.svg)](http://eepurl.com/bD4qkf)

Convert images into [spritesheets][] and coordinate maps.

[spritesheets]: http://en.wikipedia.org/wiki/Sprite_%28computer_graphics%29#Sprites_by_CSS

`spritesmith` is also available as:

- [grunt plugin](https://github.com/twolfson/grunt-spritesmith)
- [gulp plugin](https://github.com/twolfson/gulp.spritesmith)
- [CLI utility](https://github.com/bevacqua/spritesmith-cli)

A folder of icons processed by `spritesmith`:

![Fork icon][fork-icon] ![+][]
![GitHub icon][github-icon] ![+][]
![Twitter icon][twitter-icon] ![=][]

[fork-icon]: docs/fork.png
[github-icon]: docs/github.png
[twitter-icon]: docs/twitter.png
[+]: docs/plus.png
[=]: docs/equals.png

generates a spritesheet:

![spritesheet](docs/spritesheet.png)

and a coordinate map:

```js
{
  "/home/todd/github/spritesmith/docs/fork.png": {
    "x": 0,
    "y": 0,
    "width": 32,
    "height": 32
  },
  "/home/todd/github/spritesmith/docs/github.png": {
    "x": 32,
    "y": 0,
    "width": 32,
    "height": 32
  },
  // ...
}
```

### Do you like `spritesmith`?
[Support us via donations][support-us] or [spread word on Twitter][twitter]

[support-us]: http://bit.ly/support-spritesmith-1
[twitter]: https://twitter.com/intent/tweet?text=Spritesheets%20made%20easy%20via%20spritesmith&url=https%3A%2F%2Fgithub.com%2Ftwolfson%2Fspritesmith&via=twolfsn

## Breaking changes in 2.0.0
We have moved from `result.image` being a binary string to it being a `Buffer`. This is to use more canonical conventions in Node.js.

We have moved from [spritesmith-engine-spec@1.1.0][] to [spritesmith-engine-spec@2.0.0][]. This means if you use an custom engine (e.g. `gmsmith`, `canvassmith`), then you will need to upgrade it.

```bash
npm install my-engine-smith@latest --save-dev
```

By upgrading the engine, we added support for [Vinyl][] objects via `src` as well as future-proof ourselves for forwarding streaming outputs.

[spritesmith-engine-spec@1.1.0]: https://github.com/twolfson/spritesmith-engine-spec/tree/1.1.0
[spritesmith-engine-spec@2.0.0]: https://github.com/twolfson/spritesmith-engine-spec/tree/2.0.0

## Breaking changes in 3.0.0
We have updated our API to return streams for images. This required moving to a `constructor` and splitting apart image creation and processing.

We have maintained legacy support for `spritesmith` via `Spritesmith.run` which has an identical API to the `spritesmith` function in `spritesmith<3.0.0`.

```js
// Before
var spritesmith = require('spritesmith');
spritesmith({src: sprites}, function handleResult (err, result) { /* ... */ });

// After
var Spritesmith = require('spritesmith');
Spritesmith.run({src: sprites}, function handleResult (err, result) { /* ... */ });
```

## Getting started
`spritesmith` can be installed via npm: `npm install spritesmith`

```js
// Load in dependencies
var Spritesmith = require('spritesmith');

// Generate our spritesheet
var sprites = ['fork.png', 'github.png', 'twitter.png'];
Spritesmith.run({src: sprites}, function handleResult (err, result) {
  result.image; // Buffer representation of image
  result.coordinates; // Object mapping filename to {x, y, width, height} of image
  result.properties; // Object with metadata about spritesheet {width, height}
});
```

### Usage with streaming output
We support streaming output by breaking down `run` into 2 parts:

```js
// Load in dependencies
var Spritesmith = require('spritesmith');

// Create a new spritesmith and process our images
var sprites = ['fork.png', 'github.png', 'twitter.png'];
var spritesmith = new Spritesmith();
spritesmith.createImages(sprites, function handleImages (err, images) {
  images[0].width; // Width of image
  images[0].height; // Height of image

  // Create our result
  var result = spritesmith.processImages(images);
  result.image; // Readable stream outputting image
  result.coordinates; // Object mapping filename to {x, y, width, height} of image
  result.properties; // Object with metadata about spritesheet {width, height}
});
```

## Documentation
`spritesmith` exports a `Spritesmith` constructor as its `module.exports`.

If you would like a faster build time or need to support an obscure image format, see `params.engine`.

If you would like to adjust how images are laid out, see `params.algorithm` and `params.algorithmOpts`.

### `Spritesmith.run(params, callback)`
Helper function that initializes a new `Spritesmith` instance, creates images, and processes them into a spritesheet

- params `Object` - Container for parameters
    - src `String[]|Object[]` - Same as `src` for `spritesmith.createImages`
    - All other parameters accepted by `new Spritesmith` or `processImages` should be passed in here (e.g. `engine`, `algorithm`)
- callback `Function` - Error-first function that receives compiled spritesheet and information
    - `callback` should have signature `function (err, result)`
    - err `Error|null` - If an error occurred, this will be it
    - result `Object` - Container for result items
        - Same signature as content returned by `spritesmith.processImages` (i.e. `{image, coordinates, properties}`)
        - image `Buffer` - In-memory representation of image
        - coordinates `Object` - Same as `coordinates` returned by `spritesmith.processImages`
        - properties `Object` - Same as `properties` returned by `spritesmith.processImages`

### `new Spritesmith(params)`
Constructor for a new `Spritesmith` instance

- params `Object` - Container for parameters
    - engine `String|Object` - Optional engine override to use
        - By default we use [`pixelsmith`][], a node-based `spritesmith` engine
        - An example usage of `engine` can be found in the [Examples section](#engine)
        - For more engine options, see the [Engines section](#engines)
    - engineOpts `Object` - Options to pass through to engine for settings
        - For example `phantomjssmith` accepts `timeout` via `{engineOpts: {timeout: 10000}}`
        - See your engine's documentation for available options

[`pixelsmith`]: https://github.com/twolfson/pixelsmith

### `spritesmith.createImages(src, callback)`
Interpret images via the `spritesmith` engine

- src `String[]|Object[]` - Array of filepaths for images to include in spritesheet
    - If a `String` is provided, then it's used as the image's filepath
    - If an `Object` is provided, then it should be a [Vinyl][] object pointing to the source image
        - Depending on the engine, we may/may not use the contents (e.g. `gmsmith` uses filepaths only)
- callback `Function` - Error-first function that receives compiled spritesheet and map
    - `callback` should have signature `function (err, images)`
    - err `Error|null` - If an error occurred, this will be it
    - images `Object[]` - Array of processed images
        - Each `image` will be a proprietary object for the engine
        - Each `image` will line up with the specification from [spritesmith-engine-spec][spec-createImages]
        - image `Object` - Metadata container about corresponding input image at same index
            - height `Number` - Height in pixels of corresponding input image at same index
            - width `Number` - Width in pixels of corresponding input image at same index

[Vinyl]: https://github.com/gulpjs/vinyl
[spec-createImages]: https://github.com/twolfson/spritesmith-engine-spec/tree/2.0.0#enginecreateimagesimages-cb

### `spritesheet.processImages(images, options)`
Place interpretted images on a canvas and export spritesheet

- images `Object[]` - Images generated via `spritesmith.createImages`
- options `Object` - Container for options
    - padding `Number` - Padding to use between images
        - For example if `2` is provided, then there will be a `2px` gap to the right and bottom between each image
        - An example usage of `padding` can be found in the [Examples section](#padding)
    - exportOpts `Mixed` - Options to pass through to engine for export
        - For example `gmsmith` supports `quality` via `{exportOpts: {quality: 75}}`
        - See your engine's documentation for available options
    - algorithm `String` - Optional algorithm to pack images with
        - By default we use `binary-tree` which packs images as efficiently as possible
        - An example usage of `algorithm` can be found in the [Examples section](#algorithm)
        - For more algorithm options, see the [Algorithms section](#algorithms)
    - algorithmOpts `Object` - Optional algorithm options to pass through to algorithm for layout
        - For example `top-down` supports ignoring sorting via `{algorithmOpts: {sort: false}}`
        - See your algorithm's documentation for available options
            - https://github.com/twolfson/layout#algorithms

**Returns:**

- result `Object` - Container for result information
    - image `ReadableStream` - [Readable stream][] outputting generated image contents
    - coordinates `Object` - Map from filepath to coordinate information between original sprite and spritesheet
        - `filepath` will be the same as provided in `params.src`
        - [filepath] `Object` - Container for coordinate information
            - For those keeping track, this is `result.coordinates[filepath]`
            - x `Number` - Horizontal position of top-left corner of original sprite on spritesheet
            - y `Number` - Vertical position of top-left corner of original sprite on spritesheet
            - width `Number` - Width of original sprite
            - height `Number` - Height of original sprite
    - properties `Object` - Container for information about spritesheet
        - width `Number` - Width of the spritesheet
        - height `Number` - Height of the spritesheet

[Readable stream]: https://nodejs.org/api/stream.html#stream_class_stream_readable

### Algorithms
Images can be laid out in different fashions depending on the algorithm. We use [`layout`][] to provide you as many options as possible. At the time of writing, here are your options for `params.algorithm`:

[`layout`]: https://github.com/twolfson/layout

|         `top-down`        |          `left-right`         |         `diagonal`        |           `alt-diagonal`          |          `binary-tree`          |
|---------------------------|-------------------------------|---------------------------|-----------------------------------|---------------------------------|
| ![top-down][top-down-img] | ![left-right][left-right-img] | ![diagonal][diagonal-img] | ![alt-diagonal][alt-diagonal-img] | ![binary-tree][binary-tree-img] |

[top-down-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/top-down.png
[left-right-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/left-right.png
[diagonal-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/diagonal.png
[alt-diagonal-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/alt-diagonal.png
[binary-tree-img]: https://raw.githubusercontent.com/twolfson/layout/2.0.2/docs/binary-tree.png

More information can be found in the [`layout`][] documentation:

https://github.com/twolfson/layout

### Engines
An engine can greatly improve the speed of your build (e.g. `canvassmith`) or support obscure image formats (e.g. `gmsmith`).

All `spritesmith` engines adhere to a common specification:

https://github.com/twolfson/spritesmith-engine-spec

This repository adheres to specification version: **2.0.0**

Below is a list of known engines with their tradeoffs:

#### pixelsmith
[`pixelsmith`][] is a `node` based engine that runs on top of [`get-pixels`][] and [`save-pixels`][].

[`get-pixels`]: https://github.com/mikolalysenko/get-pixels
[`save-pixels`]: https://github.com/mikolalysenko/save-pixels

**Key differences:** Doesn't support uncommon image formats (e.g. `tiff`) and not as fast as a compiled library (e.g. `canvassmith`).

#### phantomjssmith
[`phantomjssmith`][] is a [phantomjs][] based engine. It was originally built to provide cross-platform compatibility but has since been succeeded by [`pixelsmith`][].

**Requirements:** [phantomjs][] must be installed on your machine and on your `PATH` environment variable. Visit [the phantomjs website][phantomjs] for installation instructions.

**Key differences:** `phantomjs` is cross-platform and supports all image formats.

[`phantomjssmith`]: https://github.com/twolfson/phantomjssmith
[phantomjs]: http://phantomjs.org/

#### canvassmith
[`canvassmith`][] is a [node-canvas][] based engine that runs on top of [Cairo][].

**Requirements:** [Cairo][] and [node-gyp][] must be installed on your machine.

Instructions on how to install [Cairo][] are provided in the [node-canvas wiki][].

[node-gyp][] should be installed via `npm`:

```bash
npm install -g node-gyp
```

**Key differences:** `canvas` has the best performance (useful for over 100 sprites). However, it is `UNIX` only.

[`canvassmith`]: https://github.com/twolfson/canvassmith
[node-canvas]: https://github.com/learnboost/node-canvas
[Cairo]: http://cairographics.org/
[node-canvas wiki]: (https://github.com/LearnBoost/node-canvas/wiki/_pages
[node-gyp]: https://github.com/TooTallNate/node-gyp/

#### gmsmith
[`gmsmith`][] is a [`gm`][] based engine that runs on top of either [Graphics Magick][] or [Image Magick][].

**Requirements:** Either [Graphics Magick][] or [Image Magick][] must be installed on your machine.

For the best results, install from the site rather than through a package manager (e.g. `apt-get`). This avoids potential transparency issues which have been reported.

[Image Magick][] is implicitly discovered. However, you can explicitly use it via `engineOpts`

```js
{
  engineOpts: {
    imagemagick: true
  }
}
```

**Key differences:** `gmsmith` allows for configuring image quality whereas others do not.

[`gmsmith`]: https://github.com/twolfson/gmsmith
[`gm`]: https://github.com/aheckmann/gm
[Graphics Magick]: http://www.graphicsmagick.org/
[Image Magick]: http://imagemagick.org/

## Examples
### Algorithm
This is an example of using a custom layout via the `alt-diagonal` algorithm.

```js
// Load in dependencies
var fs = require('fs');
var Spritesmith = require('spritesmith');

// Generate our spritesheet
Spritesmith.run({
  src: [
    __dirname + '/fork.png',
    __dirname + '/github.png',
    __dirname + '/twitter.png'
  ],
  algorithm: 'alt-diagonal'
}, function handleResult (err, result) {
  // If there was an error, throw it
  if (err) {
    throw err;
  }

  // Output the image
  fs.writeFileSync(__dirname + '/alt-diagonal.png', result.image);
  result.coordinates, result.properties; // Coordinates and properties
});
```

**Result:**

![alt-diagonal spritesheet](docs/alt-diagonal.png)

### Engine
This is an example of using a custom engine (`canvassmith` in this case).

```js
// Inside package.json
{
    "dependencies": {
        "canvassmith": "~0.2.4"
    }
}
```

```js
// In our script
// Load in dependencies
var fs = require('fs');
var Spritesmith = require('spritesmith');

// Generate our spritesheet
Spritesmith.run({
  src: [
    __dirname + '/fork.png',
    __dirname + '/github.png',
    __dirname + '/twitter.png'
  ],
  engine: require('canvassmith')
}, function handleResult (err, result) {
  // If there was an error, throw it
  if (err) {
    throw err;
  }

  // Output the image
  fs.writeFileSync(__dirname + '/canvassmith.png', result.image);
  result.coordinates, result.properties; // Coordinates and properties
});
```

**Result:**

![canvassmith spritesheet](docs/canvassmith.png)

### Padding
This is an example of adding padding between images.

```js
// Load in dependencies
var fs = require('fs');
var Spritesmith = require('spritesmith');

// Generate our spritesheet
Spritesmith.run({
  src: [
    __dirname + '/fork.png',
    __dirname + '/github.png',
    __dirname + '/twitter.png'
  ],
  padding: 20 // Exaggerated for visibility, normally 1 or 2
}, function handleResult (err, result) {
  // If there was an error, throw it
  if (err) {
    throw err;
  }

  // Output the image
  fs.writeFileSync(__dirname + '/padding.png', result.image);
  result.coordinates, result.properties; // Coordinates and properties
});
```

**Result:**

![padding spritesheet](docs/padding.png)

## Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via `npm run lint` and test via `npm test`.

## Attribution
[GitHub][github-icon] and [Twitter][twitter-icon] icons were taken from [Alex Peattie's JustVector Social Icons][justvector].

[Fork][noun-fork-icon] designed by [P.J. Onori][onori] from The Noun Project

[Plus][+] and [Equals][=] icons were built using the [Ubuntu Light typeface][ubuntu-light].

[justvector]: http://alexpeattie.com/projects/justvector_icons/
[noun-fork-icon]: http://thenounproject.com/noun/fork/#icon-No2813
[onori]: http://thenounproject.com/somerandomdude
[ubuntu-light]: http://font.ubuntu.com/

## License
Copyright (c) 2012 Todd Wolfson

Licensed under the MIT license.

---
_Source: https://npm.io/package/spritesmith · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._