npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@olenzilla/tailwindcss-plugin-spritesmith

v1.1.4

Published

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.

Downloads

317

Readme

npm Commitizen friendly

NPM

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

  • 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!