You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
101 lines
3.9 KiB
Markdown
101 lines
3.9 KiB
Markdown
10 months ago
|
# vite-plugin-tailwind-purgecss
|
||
|
|
|
||
|
|
[](https://www.npmjs.com/package/vite-plugin-tailwind-purgecss)
|
||
|
|
[](https://github.com/AdrianGonz97/vite-plugin-tailwind-purgecss/blob/main/LICENSE)
|
||
|
|
|
||
|
|
A simple vite plugin that **thoroughly** purges excess CSS using [PurgeCSS](https://purgecss.com/). This package should be used in combination with [Tailwind](https://tailwindcss.com/) and a Tailwind UI component library such as [Skeleton](https://skeleton.dev) or [Flowbite](https://flowbite.com/).
|
||
|
|
|
||
|
|
## ⚠ Notice ⚠
|
||
|
|
|
||
|
|
This package is still very **experimental**. Breaking changes can occur at any time. We'll stabilize once we hit a `1.0.0` release.
|
||
|
|
|
||
|
|
## Motivation
|
||
|
|
|
||
|
|
Tailwind UI component libraries are fantastic and are a joy to work with, but they come with an important caveat. The downside to them is that all of the Tailwind classes that are used in their provided components are _always_ generated, even if you don't import and use any of their components. This leads to a larger than necessary CSS bundle.
|
||
|
|
|
||
|
|
This is a limitation of how Tailwind works with it's `content` field in its config. Tailwind searches through all of the files that are specified in `content`, uses a regex to find any possible selectors, and generates their respective classes. There's no treeshaking and no purging involved.
|
||
|
|
|
||
|
|
## Why not use `postcss-purgecss` or `rollup-plugin-purgecss`?
|
||
|
|
|
||
|
|
PurgeCSS provides a suite of plugins that do a well enough job for _most_ projects. However, plugins such as [postcss-purgecss](https://github.com/FullHuman/purgecss/tree/main/packages/postcss-purgecss) and [rollup-plugin-purgecss](https://github.com/FullHuman/purgecss/tree/main/packages/rollup-plugin-purgecss) take a rather naive approach to selector extraction. Just like how Tailwind generates its classes, they _only_ analyze the content and files that are passed to them through their `content` fields, which means that if you pass a UI library to it, none of the selectors that are **unused** in your project will be properly purged.
|
||
|
|
|
||
|
|
## How it works
|
||
|
|
|
||
|
|
Ideally, we'd like to keep the selectors that are only being used in your project. We accomplish by analyzing the emitted JS chunks that are generated by Rollup, which only include the modules that are actually used in your project, and extracting out any of their possible selectors. From there, we can pass along the selectors to PurgeCSS for final processing.
|
||
|
|
|
||
|
|
Using `vite-plugin-tailwind-purgecss` with [Skeleton](https://skeleton.dev), we're able to reduce the CSS bundle size of Skeleton's [Barebones Template](https://github.com/skeletonlabs/skeleton-template-bare) from:
|
||
|
|
```
|
||
|
|
92.50 kB │ gzip: 12.92 kB
|
||
|
|
```
|
||
|
|
down to:
|
||
|
|
```
|
||
|
|
27.29 kB │ gzip: 5.40 kB
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
### Installation
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm i -D vite-plugin-tailwind-purgecss
|
||
|
|
```
|
||
|
|
|
||
|
|
### Add to Vite
|
||
|
|
|
||
|
|
```ts
|
||
|
|
// vite.config.ts
|
||
|
|
import { purgeCss } from 'vite-plugin-tailwind-purgecss';
|
||
|
|
|
||
|
|
const config: UserConfig = {
|
||
|
|
plugins: [sveltekit(), purgeCss()],
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
### Safelisting
|
||
|
|
|
||
|
|
If selectors that shouldn't be purged are being removed, simply add them to the `safelist`.
|
||
|
|
|
||
|
|
```ts
|
||
|
|
// vite.config.ts
|
||
|
|
import { purgeCss } from 'vite-plugin-tailwind-purgecss';
|
||
|
|
|
||
|
|
const config: UserConfig = {
|
||
|
|
plugins: [
|
||
|
|
sveltekit(),
|
||
|
|
purgeCss({
|
||
|
|
safelist: {
|
||
|
|
// any selectors that begin with "hljs-" will not be purged
|
||
|
|
greedy: [/^hljs-/],
|
||
|
|
},
|
||
|
|
}),
|
||
|
|
],
|
||
|
|
};
|
||
|
|
```
|
||
|
|
|
||
|
|
Alternatively, if you'd like to safelist selectors directly in your stylesheets, you can do so by adding special comments:
|
||
|
|
|
||
|
|
```css
|
||
|
|
/*! purgecss start ignore */
|
||
|
|
|
||
|
|
h1 {
|
||
|
|
color: red;
|
||
|
|
}
|
||
|
|
|
||
|
|
h2 {
|
||
|
|
color: blue;
|
||
|
|
}
|
||
|
|
|
||
|
|
/*! purgecss end ignore */
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also safelist selectors directly in the declaration block as well:
|
||
|
|
|
||
|
|
```css
|
||
|
|
h3 {
|
||
|
|
/*! purgecss ignore current */
|
||
|
|
color: pink;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
For further configuration, you can learn more [here](https://purgecss.com/configuration.html).
|