{"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,"search_vec":"'1.1.0':29 '2018':30,37 '4':88 '5':95 'altern':54 'build':45 'cadenc':33 'commit':35 'convert':7 'current':25 'dedic':61 'differenti':39 'earlier':90 'elimin':47 'equival':69 'file':78 'file-load':77 'gaze':74 'generat':16,42,82 'gulp':68 'gulp.spritesmith':65 'gulp/grunt':52 'icon':99 'imag':11,84 'incompat':92 'integr':40 'javascript':98 'key':38 'last':34 'like':91 'loader':79 'low':31 'mixin':18 'mode':72 'modif':97 'need':49 'pipelin':46 'plugin':5,64 'releas':32 'requir':75 'sass/less/stylus':17 'separ':51,76 'set':9 'sprite':41,63,83,100 'spritesheet':14,23 'spritesheet-templ':22 'spritesmith':3,20,57,101 'stabl':26 'support':70 'task':53 'templat':24 'use':19 'version':27 'via':73 'watch':71 'webpack':2,4,44,56,62,87,94,102 'webpack-spritesmith':1,55 'without':96 'work':85","created_at":"2026-04-25T11:25:13.400971+00:00","updated_at":"2026-04-25T11:25:13.400971+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/mixtur/webpack-spritesmith","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/webpack-spritesmith","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-24","install_tag":null}}