webpack-spritesmith

1.1.0 verified Sat Apr 25 auth: no javascript maintenance

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.

Common errors

error Error: Cannot find module 'spritesmith' ↓

cause peer dependency spritesmith not installed

fix

npm install spritesmith --save-dev

error TypeError: Cannot read property 'addChunk' of undefined ↓

cause Incompatible with webpack 5 (plugin API changed)

fix

Migrate to webpack 4 or use a maintained fork like 'webpack-spritesmith2'.

error Error: SpritesmithPlugin is not a constructor ↓

cause Incorrect import syntax (ES module import used on CommonJS module)

fix

Use const SpritesmithPlugin = require('webpack-spritesmith'); instead of import.

error Module not found: Error: Can't resolve 'sprite.png' in ... ↓

cause Missing image file in output or incorrect resolve.modules

fix

Ensure target.image path is correct and file-loader or asset module handles the PNG file. Add the output directory to resolve.modules.

Warnings

breaking 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. ↓

fix Consider forking or using an alternative; test with webpack 5 before using in production.

deprecated file-loader is recommended for the sprite image but is deprecated in favor of asset modules in webpack 5. ↓

fix Use asset modules (type: 'asset/resource') instead of file-loader in webpack 5 configs.

gotcha 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. ↓

fix Add a rule for PNG images using file-loader or asset module, and ensure resolve.modules includes the output directory.

gotcha 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. ↓

fix Set cssImageRef to '~sprite.png' (or the relative path from CSS to image) and ensure the image is in a resolved module path.

breaking Incompatible with webpack 4's optimization.splitChunks if not configured carefully; may duplicate sprite output. ↓

fix Ensure the sprite plugin runs only once; consider using webpack.optimize.LimitChunkCountPlugin or similar.

Install

npm install webpack-spritesmith

yarn add webpack-spritesmith

pnpm add webpack-spritesmith

Imports

SpritesmithPlugin

wrong

import SpritesmithPlugin from 'webpack-spritesmith';

correct

const SpritesmithPlugin = require('webpack-spritesmith');

Package does not provide ES module exports; use CommonJS require.

default

wrong

import * as SpritesmithPlugin from 'webpack-spritesmith';

correct

const SpritesmithPlugin = require('webpack-spritesmith');

Default export is CommonJS, not named.

SpritesmithPlugin

wrong

const SpritesmithPlugin = require('webpack-spritesmith').SpritesmithPlugin;

correct

const { SpritesmithPlugin } = require('webpack-spritesmith');

Correct destructuring if package exposes named export, but it's default export. This is actually wrong.

Quickstart

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.

const path = require('path');
const SpritesmithPlugin = require('webpack-spritesmith');

module.exports = {
  module: {
    rules: [
      { test: /\.styl$/, use: ['style-loader', 'css-loader', 'stylus-loader'] },
      { test: /\.png$/, use: ['file-loader?name=i/[hash].[ext]'] }
    ]
  },
  resolve: {
    modules: ["node_modules", path.resolve(__dirname, 'spritesmith-generated')]
  },
  plugins: [
    new SpritesmithPlugin({
      src: {
        cwd: path.resolve(__dirname, 'src/ico'),
        glob: '*.png'
      },
      target: {
        image: path.resolve(__dirname, 'spritesmith-generated/sprite.png'),
        css: path.resolve(__dirname, 'spritesmith-generated/sprite.styl')
      },
      apiOptions: {
        cssImageRef: "~sprite.png"
      }
    })
  ]
};