Spritesmith - Spritesheet Generator

Common errors

• TypeError: spritesmith is not a function

  cause Attempting to call `require('spritesmith')` directly as a function after version 3.0.0, which no longer exports a function at the top level.
  fix Use `Spritesmith.run()` for the legacy function-like behavior, or `new Spritesmith()` for the streaming API. Example: `const Spritesmith = require('spritesmith'); Spritesmith.run(...)`

• Error: Sorry, the spritesmith engine 'gm' could not be loaded. Please be sure you have installed it properly on your machine.

  cause The specified custom engine (e.g., 'gm' for `gmsmith`) or its underlying native dependencies (like GraphicsMagick) are not installed or are not accessible in the system's PATH.
  fix Install the required native image processing library (e.g., GraphicsMagick) and ensure the corresponding npm package for the engine (e.g., `npm install gmsmith`) is installed in your project.

• TypeError: result.image.pipe is not a function

  cause Attempting to pipe `result.image` directly in versions where it's a Buffer (pre-streaming API) or treating a Buffer as a stream. This often occurs when migrating from `grunt-spritesmith` or older `gulp.spritesmith` versions to newer streaming paradigms without adapting.
  fix If `result.image` is a Buffer, use `fs.writeFileSync()` or convert it to a stream (e.g., using `stream.Readable.from()`) if a stream is genuinely required. In `gulp.spritesmith` v6.0.0+, if Vinyl files have stream contents, use `vinyl-buffer` to convert streams to buffers if your pipeline expects buffers.

Warnings

• breaking In version 2.0.0, the `result.image` output transitioned from a binary string to a Node.js `Buffer`. Code expecting string manipulation (e.g., `result.image.toString()`) without specifying an encoding or handling Buffer methods directly will break.
  Fix: Access image data as a Buffer directly. If a string is needed, use `result.image.toString('base64')` or `result.image.toString('binary')` as appropriate, or `fs.writeFileSync('output.png', result.image)` for file operations.
• breaking Version 2.0.0 introduced an upgrade to `spritesmith-engine-spec@2.0.0`. If you are using a custom spritesmith engine (e.g., `gmsmith`, `canvassmith`), you must upgrade it to its latest compatible version to maintain functionality.
  Fix: Update your custom engine package: `npm install your-engine-smith@latest --save-dev`.
• breaking Version 3.0.0 changed the primary API. The direct `spritesmith(options, callback)` function call was removed. Legacy calls now require `Spritesmith.run(options, callback)`, while the new streaming API uses `new Spritesmith()` followed by `createImages` and `processImages`.
  Fix: For the simpler, non-streaming API, replace `spritesmith(...)` with `Spritesmith.run(...)`. For streaming, instantiate `new Spritesmith()` and use its instance methods.
• gotcha When specifying custom engines (e.g., `gmsmith`), ensure the engine and its native dependencies (like GraphicsMagick or ImageMagick for `gmsmith`) are correctly installed and accessible on the system. Failure to do so will prevent the engine from loading and `spritesmith` from functioning.
  Fix: Check the documentation for your chosen engine for installation requirements. For `gmsmith`, this typically means installing GraphicsMagick or ImageMagick system-wide. Ensure the engine package itself is installed via npm.
• gotcha In integrations with task runners like Gulp (via `gulp.spritesmith`), incorrect `imgPath` configuration can lead to broken image paths in generated CSS. The `imgPath` option specifies the URL in the CSS, which may differ from the actual file system path.
  Fix: Carefully configure `imgPath` to reflect the web-accessible URL for the spritesheet relative to your CSS, not necessarily its local file path. Ensure it matches the asset pipeline's final image URL.

Install

• npm install spritesmith npm
• yarn add spritesmith yarn
• pnpm add spritesmith pnpm

Imports

• Spritesmith
  wrong:

  import Spritesmith from 'spritesmith';

  correct:

  const Spritesmith = require('spritesmith');

  Primarily a CommonJS package. The default export is the Spritesmith constructor. Direct ESM `import` may require transpilation or a custom resolver in older Node.js environments.
• Spritesmith.run
  wrong:

  spritesmith({ src: sprites }, function handleResult (err, result) { /* ... */ });

  correct:

  Spritesmith.run({ src: sprites }, function handleResult (err, result) { /* ... */ });

  Since v3.0.0, the direct function call for spritesmith was deprecated in favor of `Spritesmith.run` for legacy compatibility, or using the `new Spritesmith()` constructor for streaming.
• new Spritesmith()

  const spritesmithInstance = new Spritesmith();

  For streaming API usage, instantiate the `Spritesmith` constructor, then use `createImages` and `processImages`.

Quickstart

This quickstart demonstrates how to generate a spritesheet from a list of image paths and save the resulting image and coordinate data to disk. It uses the `Spritesmith.run` helper function for a simplified API call.

const Spritesmith = require('spritesmith');
const path = require('path');
const fs = require('fs');

// Create dummy image files for demonstration
const dummyImageDir = path.join(__dirname, 'temp-icons');
if (!fs.existsSync(dummyImageDir)) fs.mkdirSync(dummyImageDir);
fs.writeFileSync(path.join(dummyImageDir, 'icon1.png'), Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64'));
fs.writeFileSync(path.join(dummyImageDir, 'icon2.png'), Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwAB/2N6HBYAAAAASUVORK5CYII=', 'base64'));

const sprites = [
  path.join(dummyImageDir, 'icon1.png'),
  path.join(dummyImageDir, 'icon2.png')
];

Spritesmith.run({ src: sprites }, function handleResult (err, result) {
  if (err) {
    console.error('Spritesmith error:', err);
    return;
  }

  // result.image is a Buffer representation of the generated spritesheet
  fs.writeFileSync('spritesheet.png', result.image);
  console.log('Spritesheet saved to spritesheet.png');
  console.log('Coordinates:', result.coordinates);
  console.log('Properties:', result.properties);

  // Clean up dummy images
  fs.unlinkSync(path.join(dummyImageDir, 'icon1.png'));
  fs.unlinkSync(path.join(dummyImageDir, 'icon2.png'));
  fs.rmdirSync(dummyImageDir);
});