{"id":20834,"library":"webpack-spritesmith","title":"webpack-spritesmith","description":"Webpack plugin that converts a set of images into a spritesheet and generates SASS/LESS/Stylus mixins using spritesmith and spritesheet-templates. Current stable version is 1.1.0 (2018). Low release cadence; last commit in 2018. Key differentiator: integrates sprite generation into webpack build pipeline, eliminating the need for separate gulp/grunt tasks. Alternatives: webpack-spritesmith is the only dedicated webpack sprite plugin; gulp.spritesmith is a gulp equivalent. Supports watch mode via gaze. Requires separate file-loader for the generated sprite image. Works with webpack 4 and earlier; likely incompatible with webpack 5 without modifications.","status":"maintenance","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/mixtur/webpack-spritesmith","tags":["javascript","icons","sprites","spritesmith","webpack"],"install":[{"cmd":"npm install webpack-spritesmith","lang":"bash","label":"npm"},{"cmd":"yarn add webpack-spritesmith","lang":"bash","label":"yarn"},{"cmd":"pnpm add webpack-spritesmith","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core sprite generation engine","package":"spritesmith","optional":false},{"reason":"Generates CSS/SCSS/Stylus/LESS mixins from sprite data","package":"spritesheet-templates","optional":false}],"imports":[{"note":"Package does not provide ES module exports; use CommonJS require.","wrong":"import SpritesmithPlugin from 'webpack-spritesmith';","symbol":"SpritesmithPlugin","correct":"const SpritesmithPlugin = require('webpack-spritesmith');"},{"note":"Default export is CommonJS, not named.","wrong":"import * as SpritesmithPlugin from 'webpack-spritesmith';","symbol":"default","correct":"const SpritesmithPlugin = require('webpack-spritesmith');"},{"note":"Correct destructuring if package exposes named export, but it's default export. This is actually wrong.","wrong":"const SpritesmithPlugin = require('webpack-spritesmith').SpritesmithPlugin;","symbol":"SpritesmithPlugin","correct":"const { SpritesmithPlugin } = require('webpack-spritesmith');"}],"quickstart":{"code":"const path = require('path');\nconst SpritesmithPlugin = require('webpack-spritesmith');\n\nmodule.exports = {\n  module: {\n    rules: [\n      { test: /\\.styl$/, use: ['style-loader', 'css-loader', 'stylus-loader'] },\n      { test: /\\.png$/, use: ['file-loader?name=i/[hash].[ext]'] }\n    ]\n  },\n  resolve: {\n    modules: [\"node_modules\", path.resolve(__dirname, 'spritesmith-generated')]\n  },\n  plugins: [\n    new SpritesmithPlugin({\n      src: {\n        cwd: path.resolve(__dirname, 'src/ico'),\n        glob: '*.png'\n      },\n      target: {\n        image: path.resolve(__dirname, 'spritesmith-generated/sprite.png'),\n        css: path.resolve(__dirname, 'spritesmith-generated/sprite.styl')\n      },\n      apiOptions: {\n        cssImageRef: \"~sprite.png\"\n      }\n    })\n  ]\n};","lang":"javascript","description":"Configures webpack-spritesmith to generate a sprite sheet from PNG icons and produce Stylus mixins, with file-loader for the image and resolve alias for generated files."},"warnings":[{"fix":"Consider forking or using an alternative; test with webpack 5 before using in production.","message":"Package has not been updated since 2018; compatibility with webpack 5 is not guaranteed. May break with webpack 5 due to changes in hook API.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Use asset modules (type: 'asset/resource') instead of file-loader in webpack 5 configs.","message":"file-loader is recommended for the sprite image but is deprecated in favor of asset modules in webpack 5.","severity":"deprecated","affected_versions":">=1.1.0"},{"fix":"Add a rule for PNG images using file-loader or asset module, and ensure resolve.modules includes the output directory.","message":"The generated sprite image must be handled by a file-loader or asset module; otherwise the image file won't be emitted and the CSS ref will be broken.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set cssImageRef to '~sprite.png' (or the relative path from CSS to image) and ensure the image is in a resolved module path.","message":"The cssImageRef apiOptions must reference the image path as a module request (with '~' prefix) if using resolve.modules, otherwise the CSS background-image URL may not resolve correctly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the sprite plugin runs only once; consider using webpack.optimize.LimitChunkCountPlugin or similar.","message":"Incompatible with webpack 4's optimization.splitChunks if not configured carefully; may duplicate sprite output.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"npm install spritesmith --save-dev","cause":"peer dependency spritesmith not installed","error":"Error: Cannot find module 'spritesmith'"},{"fix":"Migrate to webpack 4 or use a maintained fork like 'webpack-spritesmith2'.","cause":"Incompatible with webpack 5 (plugin API changed)","error":"TypeError: Cannot read property 'addChunk' of undefined"},{"fix":"Use const SpritesmithPlugin = require('webpack-spritesmith'); instead of import.","cause":"Incorrect import syntax (ES module import used on CommonJS module)","error":"Error: SpritesmithPlugin is not a constructor"},{"fix":"Ensure target.image path is correct and file-loader or asset module handles the PNG file. Add the output directory to resolve.modules.","cause":"Missing image file in output or incorrect resolve.modules","error":"Module not found: Error: Can't resolve 'sprite.png' in ..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}