{"id":12063,"library":"spritesmith","title":"Spritesmith - Spritesheet Generator","description":"Spritesmith is a Node.js utility for programmatically generating spritesheets and corresponding coordinate maps from individual image files. It provides a robust solution for optimizing web assets by combining multiple small images into a single larger image, reducing HTTP requests and improving load times. The current stable version is 3.5.1, and while there isn't a fixed release cadence, major versions introduce significant API changes and improvements, as seen with versions 2.0.0 and 3.0.0. A key differentiator is its pluggable engine architecture, allowing users to switch between various image processing backends like `pixelsmith` (default Node.js-based), `gmsmith`, or `canvassmith` to suit performance or format requirements. It also offers flexible output formats for coordinate data, making it adaptable for integration with various CSS preprocessors and build tools such as Grunt and Gulp via dedicated plugins, and even Webpack.","status":"active","version":"3.5.1","language":"javascript","source_language":"en","source_url":"git://github.com/twolfson/spritesmith","tags":["javascript","sprite","spritesheet","css"],"install":[{"cmd":"npm install spritesmith","lang":"bash","label":"npm"},{"cmd":"yarn add spritesmith","lang":"bash","label":"yarn"},{"cmd":"pnpm add spritesmith","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import Spritesmith from 'spritesmith';","symbol":"Spritesmith","correct":"const Spritesmith = require('spritesmith');"},{"note":"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.","wrong":"spritesmith({ src: sprites }, function handleResult (err, result) { /* ... */ });","symbol":"Spritesmith.run","correct":"Spritesmith.run({ src: sprites }, function handleResult (err, result) { /* ... */ });"},{"note":"For streaming API usage, instantiate the `Spritesmith` constructor, then use `createImages` and `processImages`.","symbol":"new Spritesmith()","correct":"const spritesmithInstance = new Spritesmith();"}],"quickstart":{"code":"const Spritesmith = require('spritesmith');\nconst path = require('path');\nconst fs = require('fs');\n\n// Create dummy image files for demonstration\nconst dummyImageDir = path.join(__dirname, 'temp-icons');\nif (!fs.existsSync(dummyImageDir)) fs.mkdirSync(dummyImageDir);\nfs.writeFileSync(path.join(dummyImageDir, 'icon1.png'), Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=', 'base64'));\nfs.writeFileSync(path.join(dummyImageDir, 'icon2.png'), Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwAB/2N6HBYAAAAASUVORK5CYII=', 'base64'));\n\nconst sprites = [\n  path.join(dummyImageDir, 'icon1.png'),\n  path.join(dummyImageDir, 'icon2.png')\n];\n\nSpritesmith.run({ src: sprites }, function handleResult (err, result) {\n  if (err) {\n    console.error('Spritesmith error:', err);\n    return;\n  }\n\n  // result.image is a Buffer representation of the generated spritesheet\n  fs.writeFileSync('spritesheet.png', result.image);\n  console.log('Spritesheet saved to spritesheet.png');\n  console.log('Coordinates:', result.coordinates);\n  console.log('Properties:', result.properties);\n\n  // Clean up dummy images\n  fs.unlinkSync(path.join(dummyImageDir, 'icon1.png'));\n  fs.unlinkSync(path.join(dummyImageDir, 'icon2.png'));\n  fs.rmdirSync(dummyImageDir);\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your custom engine package: `npm install your-engine-smith@latest --save-dev`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"For the simpler, non-streaming API, replace `spritesmith(...)` with `Spritesmith.run(...)`. For streaming, instantiate `new Spritesmith()` and use its instance methods.","message":"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`.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `Spritesmith.run()` for the legacy function-like behavior, or `new Spritesmith()` for the streaming API. Example: `const Spritesmith = require('spritesmith'); Spritesmith.run(...)`","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.","error":"TypeError: spritesmith is not a function"},{"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.","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.","error":"Error: Sorry, the spritesmith engine 'gm' could not be loaded. Please be sure you have installed it properly on your machine."},{"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.","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.","error":"TypeError: result.image.pipe is not a function"}],"ecosystem":"npm"}