@olenzilla/tailwindcss-plugin-spritesmith

A Tailwind plugin that takes folders of sprite images and uses TailwindCSS and Spritesmith with Webpack or Vite to generate image spritesheets and corresponding sprite classes as Tailwind utilities.

• Features & Highlights
• Webpack
  • Basic Usage, Webpack
  • Ideal Usage, Webpack
• Vite
  • Basic Usage, Vite
  • Ideal Usage, Vite
• Acknowledgements

Features & Highlights

• Instead of creating a CSS file with the classes for each sprite, a TailwindCSS plugin that generates TailwindCSS utilities for each sprite:
  • for a sprite image called example-a.png, you can use sprite-example-a in your templates.
  • if you also have a sprite image called example-a.jpg, you can also use sprite-example-a.jpg in your templates.
• Can be configured to make a spritesheet from a single folder of images, or separate spritesheets for each subfolder of a folder of folders of images. (Incept your spritesheets!)
• Creates a new TailwindCSS theme property called spriteWidth and spriteHeight with all the heights and widths of all your sprites, so you can add a configuration like width: ({ theme }) => ({ ...theme('spriteWidth') }), to use classes like w-sprite-example-a for just the example-a.png sprite's width.
• retina-friendly -- just pass pixelDensity: 2, to the plugin's configuration
• extremely flexible:
  • not only can you resize the sprite-example-a element if you like with things like max-w-full,
  • you can also use any sprite's height or width using h-sprite-example-a max-w-sprite-example-a on other elements, etc.
• because all sprites' classes are just TailwindCSS utilities, you can use any Tailwind variants you have configured from interactive variants like hover: to responsiveness variants like md: and the rest.
• Also, by using Tailwind's content configuration, unused sprite utilities will never be output into CSS. Therefore, this allows your builder to only include spritesheet images whose sprites are actually used in your built code.
• When used in combination with Prettier and prettier-plugin-tailwindcss, this plugin therefore allows you to have autocompletion for all sprite related classes!

Importantly, unlike the spritesheets generated by webpack-spritesmith, the sprite styles generated by this plugin can be resized because they're implemented using percentages rather than px values. So for instance, you can use max-w-[25px] sprite-example-a and it will ensure the sprite is not larger than 25px wide, without changing the sprite's aspect ratio. And if you explicitly set a width and height like w-[10px] h-[25px] sprite-example, the sprite will be deformed as you'd expect.

Webpack

Basic Usage, Webpack

In your webpack.config.ts:

import { Configuration } from 'webpack'
import { webpack as tailwindSpritesmithPlugin } from '@olenzilla/tailwindcss-plugin-spritesmith'

export default <Configuration>{
	plugins: [
		tailwindSpritesmithPlugin(
			{
				spritesheets: [
					{
						// These images:
						spriteImageGlob: 'assets/sprites/*.png',
						// Will be stitched together into a spritesheet image here:
						outputImage: 'assets/target/sprites.png',
						// Optional:
						// outputBackgroundImage(outputImage) {
						// 	return `url(${outputImage})`
						// },
					},
				],
			},
			// And all the corresponding TailwindCSS utilities will be output here:
			'tailwindcss-spritesmith-utilities.json',
		),
		// ...
	],
}

Then pass the file the Webpack plugin creates to the corresponding TailwindCSS plugin in tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
	// ...
	plugins: [
		require('@olenzilla/tailwindcss-plugin-spritesmith').tailwind(
			require('./tailwindcss-spritesmith-utilities.json'),
		),
		// ...
	],
}

Ideal Usage, Webpack

This plugin can be configured to look at a single directory that contains subdirectories of sprite images, and automatically create separate spritesheets for each subdirectory, and each set of distinct image filetypes (i.e. PNGs vs JPGs):

Your webpack.config.ts:

import { Configuration } from 'webpack'
import { vite as tailwindSpritesmithPlugin } from '@olenzilla/tailwindcss-plugin-spritesmith'

export default <Configuration>{
	plugins: [
		tailwindSpritesmithPlugin(
			{
				spritesheets: {
					spritesDirGlob: 'assets/sprites/*',
					outputDir: 'assets/sprites',
					// Optional:
					// outputImage(spritesDir: Path, extension: string) {
					// 	return path.join(
					// 	'assets',
					// 	`${spritesDir.name}.${ext}`,
					// )
					// },
					// extensions: ['png', 'jpg'],
				},
			},
			// And all the corresponding TailwindCSS utilities will be output here:
			'tailwindcss-spritesmith-utilities.json',
		),
		// ...
	],
}

And the same tailwind.config.js as before:

/** @type {import('tailwindcss').Config} */
module.exports = {
	// ...
	plugins: [
		require('@olenzilla/tailwindcss-plugin-spritesmith').tailwind(
			require('./tailwindcss-spritesmith-utilities.json'),
		),
		// ...
	],
}

Vite

Basic Usage, Vite

In your vite.config.ts:

import { defineConfig } from 'vite'
import { vite as tailwindSpritesmithPlugin } from '@olenzilla/tailwindcss-plugin-spritesmith'

export default defineConfig({
	plugins: [
		tailwindSpritesmithPlugin(
			{
				spritesheets: [
					{
						// These images:
						spriteImageGlob: 'assets/sprites/*.png',
						// Will be stitched together into a spritesheet image here:
						outputImage: 'assets/target/sprites.png',
						// Optional:
						// outputBackgroundImage(outputImage) {
						// 	return `url(${outputImage})`
						// },
					},
				],
			},
			// And all the corresponding TailwindCSS utilities will be output here:
			'tailwindcss-spritesmith-utilities.json',
		),
		// ...
	],
})

Then pass the file the Vite plugin creates to the corresponding TailwindCSS plugin in tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
	// ...
	plugins: [
		(function () {
			try {
				return require('@olenzilla/tailwindcss-plugin-spritesmith').tailwind(
					require('./.cache/tailwindcss-spritesmith-utilities.json'),
				)
			} catch (e) {
				return {}
			}
		})(),
		// ...
	],
}

Note that we have less control over when exactly the Vite plugin runs relative to the tailwind plugin in things like NuxtJS, so it's important to write it this way to allow the .json file to not exist initially, and then automatically rebuild once it does.

Ideal Usage, Vite

This plugin can be configured to look at a single directory that contains subdirectories of sprite images, and automatically create separate spritesheets for each subdirectory, and each set of distinct image filetypes (i.e. PNGs vs JPGs):

Your vite.config.ts:

import { defineConfig } from 'vite'
import { vite as tailwindSpritesmithPlugin } from '@olenzilla/tailwindcss-plugin-spritesmith'

export default defineConfig({
	plugins: [
		tailwindSpritesmithPlugin(
			{
				spritesheets: {
					spritesDirGlob: 'assets/sprites/*',
					outputDir: 'assets/sprites',
					// Optional:
					// outputImage(spritesDir: Path, extension: string) {
					// 	return path.join(
					// 	'assets',
					// 	`${spritesDir.name}.${ext}`,
					// )
					// },
					// extensions: ['png', 'jpg'],
				},
			},
			// And all the corresponding TailwindCSS utilities will be output here:
			'tailwindcss-spritesmith-utilities.json',
		),
		// ...
	],
})

And the same tailwind.config.js as before:

/** @type {import('tailwindcss').Config} */
module.exports = {
	// ...
	plugins: [
		(function () {
			try {
				return require('@olenzilla/tailwindcss-plugin-spritesmith').tailwind(
					require('./.cache/tailwindcss-spritesmith-utilities.json'),
				)
			} catch (e) {
				return {}
			}
		})(),
		// ...
	],
}

Note that we have less control over when exactly the Vite plugin runs relative to the tailwind plugin in things like NuxtJS, so it's important to write it this way to allow the .json file to not exist initially, and then automatically rebuild once it does.

Acknowledgements

Thanks to @evont for vite-plugin-spritesmith and of course @twolfson for spritesmith and @mixtur for webpack-spritesmith!