nuxt-spritesmith

nuxt-spritesmith

A Nuxt(3) module for generate sprite image icons via spritesmith

• ✨  Release Notes

Features

• Powered by spritesmith.
• Support Multi sprite sheet generation.

Quick Setup

1. Add nuxt-spritesmith dependency to your project

# Using pnpm
pnpm add -D nuxt-spritesmith

# Using yarn
yarn add --dev nuxt-spritesmith

# Using npm
npm install --save-dev nuxt-spritesmith

2. Add nuxt-spritesmith to the modules section of nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-spritesmith'
  ],
  // custom nuxt-spritesmith options
  spritesmith: {
    engine: 'sharpsmith',
    engineOpts: {
      concurrentFileLimit: 4
    }
  }
})

You can also pass an engine constructor directly:

import SharpSmith from 'sharpsmith'

export default defineNuxtConfig({
  modules: ['nuxt-spritesmith'],
  spritesmith: {
    engine: SharpSmith,
  },
})

3. Put your icons in ~/assets/sprites folder.

4. Using your sprite icon.

<template>
  <div>
     <span class="sprite-some sprite-some--your-icon-name"></span>
  </div>
</template>

That's it! You can now use nuxt-spritesmith in your Nuxt app ✨

Custom engine

By default, the module uses the sharpsmith engine. You can explicitly select another installed engine, such as pixelsmith, by package name:

pnpm add -D nuxt-spritesmith sharpsmith

export default defineNuxtConfig({
  modules: ['nuxt-spritesmith'],
  spritesmith: {
    engine: 'sharpsmith',
    engineOpts: {
      concurrentFileLimit: 4,
    },
  },
})

The engine constructor can also be passed directly:

import SharpSmith from 'sharpsmith'

export default defineNuxtConfig({
  modules: ['nuxt-spritesmith'],
  spritesmith: {
    engine: SharpSmith,
  },
})

engineOpts is forwarded to the selected engine constructor. The engine must implement spritesmith-engine-spec@2.0.0.

Options

The module scans the first-level directories under srcDir. For example, assets/sprites/payment/*.png generates public/sprites/payment.png and the corresponding CSS classes use the configured prefix.

When Retina support is enabled, files ending with @2x are grouped into a second sprite sheet, such as payment@2x.png, and CSS is generated with a device-pixel-ratio media query.

Development

# Install dependencies
pnpm install

# Generate type stubs
pnpm dev:prepare

# Develop with the playground
pnpm dev

# Build the playground
pnpm dev:build

# Run ESLint
pnpm lint

# Run Vitest
pnpm test
pnpm test:watch

# Release new version
npm run release

The test suite uses Vitest and Nuxt Test Utils. It covers SSR rendering, standard and Retina sprite generation, engine configuration, generated CSS, and cleanup of temporary fixture files.