{"id":22844,"library":"vite-plugin-spritesmith","title":"vite-plugin-spritesmith","description":"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.","status":"active","version":"0.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/evont/vite-plugin-spritesmith","tags":["javascript","rollup","rollup-plugin","vite-plugin","rollup-plugin-spritesmith","spritesmith","sprite"],"install":[{"cmd":"npm install vite-plugin-spritesmith","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-spritesmith","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-spritesmith","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core sprite generation engine","package":"spritesmith","optional":false},{"reason":"Generates CSS/SASS/LESS/Stylus mixins from spritesmith output","package":"spritesheet-templates","optional":false},{"reason":"Used to find source images matching glob pattern","package":"glob","optional":false},{"reason":"Used for file watching in watch mode","package":"gaze","optional":true}],"imports":[{"note":"Default import; the plugin is exported as ESM default. CommonJS require may work depending on bundler.","wrong":"const Spritesmith = require('vite-plugin-spritesmith')","symbol":"Spritesmith","correct":"import Spritesmith from 'vite-plugin-spritesmith'"},{"note":"No named export; must use default import.","wrong":"import { vitePluginSpritesmith } from 'vite-plugin-spritesmith'","symbol":"vitePluginSpritesmith","correct":"import Spritesmith from 'vite-plugin-spritesmith'"},{"note":"TypeScript users should import Options type for type safety; it's not a runtime export.","wrong":"import { Options } from 'vite-plugin-spritesmith'","symbol":"pluginOptions type","correct":"import type { Options } from 'vite-plugin-spritesmith'"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite';\nimport Spritesmith from 'vite-plugin-spritesmith';\n\nexport default defineConfig({\n  plugins: [\n    Spritesmith({\n      watch: true,\n      src: {\n        cwd: './src/assets/sprites',\n        glob: '*.png',\n      },\n      target: {\n        image: './src/assets/target/sprite.png',\n        css: [\n          ['./src/assets/style/sprite.scss', { format: 'handlebars_based_template' }],\n        ],\n      },\n      apiOptions: {\n        cssImageRef: 'assets/target/sprite.png',\n        spritesheet_info: {\n          name: 'mysprite',\n          format: 'handlebars_based_template',\n        },\n      },\n      customTemplates: {\n        handlebars_based_template: './src/scss.handlebars',\n      },\n    }),\n  ],\n});","lang":"javascript","description":"Complete Vite config using the plugin with watch mode, glob source, SASS output with custom Handlebars template, and explicit cssImageRef."},"warnings":[{"fix":"Always set apiOptions.cssImageRef to the correct public path relative to where your CSS will be served.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use consistent interpolation variables (e.g., [name], [hash]) in both target.image and apiOptions.cssImageRef.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Version 0.1.0 had an incompatible config structure for target.css; some users experienced silent failures when passing plain strings.","severity":"breaking","affected_versions":"0.1.0"},{"fix":"Do not rely on retina options; if you need retina sprites, consider alternative plugins or manual processing.","message":"The retina support options are documented but not yet implemented; apiOptions.retina and related names have no effect.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Set watch: false or ensure your development environment uses a supported file system (NTFS, ext4, APFS).","message":"watch mode depends on the 'gaze' package which may not work reliably on all file systems (e.g., network drives, WSL1).","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Ensure target.image is a string path to the output sprite image file.","cause":"The target.image option is missing or set to undefined.","error":"TypeError: Cannot read properties of undefined (reading 'image')"},{"fix":"Install gaze: npm install -D gaze, or set watch: false.","cause":"watch: true is set but the optional dependency 'gaze' is not installed.","error":"Error: Cannot find module 'gaze'"},{"fix":"Add a valid customTemplates entry mapping the format name to a Handlebars template file path.","cause":"You specified a custom template but did not provide the actual template file path in customTemplates.","error":"Error: Unrecognized format: 'handlebars_based_template'"},{"fix":"Create the output directory manually before building, or ensure your build tool creates it.","cause":"The directory for the target CSS file does not exist.","error":"Error: ENOENT: no such file or directory, open '...sprite.scss'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}