rollup-plugin-sprite

0.1.2 verified Mon Apr 27 auth: no javascript maintenance

A Rollup plugin that generates a sprite sheet from a set of images using spritesmith and outputs corresponding SASS/LESS/Stylus/CSS mixins. Current stable version: 0.1.2. Infrequently updated; last commit 2019. Differentiates by integrating sprite generation into the Rollup build pipeline, automating the creation of CSS sprites and mixins directly from source images. Compared to standalone tools like grunt-sprite or gulp.spritesmith, this plugin offers seamless bundling with Rollup, reducing build configuration overhead.

Common errors

error Error: Cannot find module 'spritesmith' ↓

cause Missing dependency 'spritesmith' not auto-installed by npm.

fix

Run 'npm install spritesmith' to install it as a direct dependency.

error TypeError: spritesmith is not a function ↓

cause Using named import instead of default import.

fix

Use default import: import spritesmith from 'rollup-plugin-sprite'

error Error: 'buildStart' hook called without context ↓

cause Rollup version mismatch; hook API changed in v2.

fix

Use Rollup v1.x or upgrade plugin.

Warnings

deprecated Package last updated in 2019; may not support newer Rollup versions (v3+). ↓

fix Consider using alternative sprite plugins like 'rollup-plugin-sprite-svg' or update manually.

gotcha The 'cssImageRef' option must match the 'target.image' interpolation for correct path resolution. ↓

fix Ensure both use same interpolations (e.g., if target.image uses [hash], cssImageRef should too).

gotcha The plugin uses spritesmith internally; ensure spritesmith dependencies (e.g., canvas) are installed for image processing. ↓

fix Install optional dependencies like 'canvas' if default image processing fails.

breaking Rollup configuration hook 'buildStart' signature changed in v2 causing plugin failure. ↓

fix Update plugin or use Rollup v1.x or v3.x with compatibility wrapper.

Install

npm install rollup-plugin-sprite

yarn add rollup-plugin-sprite

pnpm add rollup-plugin-sprite

Imports

default
wrong
```
const spritesmith = require('rollup-plugin-sprite')
```
correct
```
import spritesmith from 'rollup-plugin-sprite'
```
CommonJS require may not work if the package is ESM-only; check bundler configuration. Default import is recommended.
spritesmith (named export)
wrong
```
import spritesmith from 'rollup-plugin-sprite'
```
correct
```
import { spritesmith } from 'rollup-plugin-sprite'
```
The package exports a default function; named export 'spritesmith' does not exist. Use default import.
SpritePlugin (TypeScript type)
wrong
```
import { SpritePlugin } from 'rollup-plugin-sprite'
```
correct
```
import type { SpritePlugin } from 'rollup-plugin-sprite'
```
If using TypeScript, import types explicitly with `import type`. Not all versions have type definitions.

Quickstart

Demonstrates basic plugin configuration: source glob, target image and CSS paths, output directory, and spritesmith options.

import spritesmith from 'rollup-plugin-sprite';
import { defineConfig } from 'rollup';

export default defineConfig({
  input: 'src/main.js',
  output: {
    dir: 'dist',
    format: 'cjs'
  },
  plugins: [
    spritesmith({
      src: {
        cwd: 'src/ui/images/sprite',
        glob: '**/*.png'
      },
      target: {
        image: 'src/ui/images/sprite.png',
        css: 'src/ui/sass/sprite.scss'
      },
      cssImageRef: '../images/sprite.png',
      output: {
        image: 'dist/images/sprite.png'
      },
      spritesmithOptions: {
        padding: 5
      }
    })
  ]
});