@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
265
Maintainers
Readme
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 usesprite-example-a
in your templates. - if you also have a sprite image called
example-a.jpg
, you can also usesprite-example-a.jpg
in your templates.
- for a sprite image called
- 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
andspriteHeight
with all the heights and widths of all your sprites, so you can add a configuration likewidth: ({ theme }) => ({ ...theme('spriteWidth') }),
to use classes likew-sprite-example-a
for just theexample-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 likemax-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.
- not only can you resize the
- 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 likemd:
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!