vite-plugin-spritesmith

0.1.1 verified Mon Apr 27 auth: no javascript

Vite plugin to generate spritesheets and CSS/SASS/LESS/Stylus mixins from image files using spritesmith and spritesheet-templates. Current version 0.1.1, initial release with basic functionality. Supports glob-based source image selection, watch mode, custom templates (Handlebars), and multiple CSS output formats. Differentiator: integrates directly with Vite build pipeline (no separate Grunt/Gulp step). Limited community adoption and few updates; suitable for simple sprite workflows but lacks advanced features like retina support or automatic CSS image ref resolution.

Common errors

error TypeError: Cannot read properties of undefined (reading 'image') ↓

cause The target.image option is missing or set to undefined.

fix

Ensure target.image is a string path to the output sprite image file.

error Error: Cannot find module 'gaze' ↓

cause watch: true is set but the optional dependency 'gaze' is not installed.

fix

Install gaze: npm install -D gaze, or set watch: false.

error Error: Unrecognized format: 'handlebars_based_template' ↓

cause You specified a custom template but did not provide the actual template file path in customTemplates.

fix

Add a valid customTemplates entry mapping the format name to a Handlebars template file path.

error Error: ENOENT: no such file or directory, open '...sprite.scss' ↓

cause The directory for the target CSS file does not exist.

fix

Create the output directory manually before building, or ensure your build tool creates it.

Warnings

gotcha cssImageRef must be set manually and must match the actual path used in your HTML/CSS; there is no automatic resolution based on target.image. ↓

fix Always set apiOptions.cssImageRef to the correct public path relative to where your CSS will be served.

gotcha When using interpolated filenames in target.image (e.g., with hash), you must also interpolate cssImageRef with the same pattern, or the CSS will reference a non-existent file. ↓

fix Use consistent interpolation variables (e.g., [name], [hash]) in both target.image and apiOptions.cssImageRef.

breaking Version 0.1.0 had an incompatible config structure for target.css; some users experienced silent failures when passing plain strings. ↓

fix Upgrade to 0.1.1 which accepts strings as well as arrays; if using 0.1.0, wrap target.css entries in arrays even for single output.

deprecated The retina support options are documented but not yet implemented; apiOptions.retina and related names have no effect. ↓

fix Do not rely on retina options; if you need retina sprites, consider alternative plugins or manual processing.

gotcha watch mode depends on the 'gaze' package which may not work reliably on all file systems (e.g., network drives, WSL1). ↓

fix Set watch: false or ensure your development environment uses a supported file system (NTFS, ext4, APFS).

Install

npm install vite-plugin-spritesmith

yarn add vite-plugin-spritesmith

pnpm add vite-plugin-spritesmith

Imports

Spritesmith
wrong
```
const Spritesmith = require('vite-plugin-spritesmith')
```
correct
```
import Spritesmith from 'vite-plugin-spritesmith'
```
Default import; the plugin is exported as ESM default. CommonJS require may work depending on bundler.

vitePluginSpritesmith

wrong

import { vitePluginSpritesmith } from 'vite-plugin-spritesmith'

correct

import Spritesmith from 'vite-plugin-spritesmith'

No named export; must use default import.

pluginOptions type
wrong
```
import { Options } from 'vite-plugin-spritesmith'
```
correct
```
import type { Options } from 'vite-plugin-spritesmith'
```
TypeScript users should import Options type for type safety; it's not a runtime export.

Quickstart

Complete Vite config using the plugin with watch mode, glob source, SASS output with custom Handlebars template, and explicit cssImageRef.

// vite.config.js
import { defineConfig } from 'vite';
import Spritesmith from 'vite-plugin-spritesmith';

export default defineConfig({
  plugins: [
    Spritesmith({
      watch: true,
      src: {
        cwd: './src/assets/sprites',
        glob: '*.png',
      },
      target: {
        image: './src/assets/target/sprite.png',
        css: [
          ['./src/assets/style/sprite.scss', { format: 'handlebars_based_template' }],
        ],
      },
      apiOptions: {
        cssImageRef: 'assets/target/sprite.png',
        spritesheet_info: {
          name: 'mysprite',
          format: 'handlebars_based_template',
        },
      },
      customTemplates: {
        handlebars_based_template: './src/scss.handlebars',
      },
    }),
  ],
});