vite-plugin-tailwind-purgecss

0.3.5 verified Mon Apr 27 auth: no javascript

Vite plugin that purges unused Tailwind CSS classes from the production bundle. Current stable version is 0.3.5, released with regular patches. The plugin targets only Tailwind-specific classes (not all CSS) and works with Tailwind v3 and component libraries like Skeleton, Flowbite, or shadcn-ui. It analyzes the Vite module graph to extract used selectors and passes them to PurgeCSS, reducing CSS size significantly (e.g., from 105 kB to 16 kB for a Skeleton template). Since v0.3.0, the default behavior is focused on Tailwind classes only, with an optional legacy mode for broader purging. Note: Tailwind v4 will make this plugin obsolete.

Common errors

error Error: The plugin purgeCss requires tailwindcss as a peer dependency but it is not installed. ↓

cause Missing tailwindcss peer dependency when using v0.3.0+.

fix

Install tailwindcss: npm install -D tailwindcss@^3.3.0

error Cannot find module 'vite-plugin-tailwind-purgecss' or its corresponding type declarations. ↓

cause Using default import (import purgeCss from '...') instead of named import.

fix

Use named import: import { purgeCss } from 'vite-plugin-tailwind-purgecss'

error Error: purgeCss is not a function ↓

cause Incorrect import (default import) in CommonJS or ESM.

fix

Use const { purgeCss } = require('vite-plugin-tailwind-purgecss') or import { purgeCss } from 'vite-plugin-tailwind-purgecss'.

Warnings

breaking v0.3.0 changed the default purging strategy to only target Tailwind-specific classes; previous behavior is opt-in via legacy mode. ↓

fix If you need the old behavior (purge all unused CSS), enable legacy mode: purgeCss({ legacy: true }).

breaking v0.3.0 added tailwindcss (v3.3.0 or higher) as a required peer dependency. ↓

fix Ensure tailwindcss@^3.3.0 is installed in your project.

breaking v0.3.0 updated plugin option types; old options may no longer be valid. ↓

fix Check the new type definition for PurgeOptions; for legacy mode use { legacy: true }.

gotcha The plugin only purges Tailwind classes by default (since v0.3.0); it does not remove other unused CSS. ↓

fix If you need broader purging, enable legacy mode or use a separate CSS purging tool.

deprecated The plugin will be unnecessary after Tailwind v4 release, which includes built-in Vite plugin and content detection. ↓

fix Plan to migrate to Tailwind v4 when it is stable and remove this plugin.

Install

npm install vite-plugin-tailwind-purgecss

yarn add vite-plugin-tailwind-purgecss

pnpm add vite-plugin-tailwind-purgecss

Imports

purgeCss

wrong

import purgeCss from 'vite-plugin-tailwind-purgecss'

correct

import { purgeCss } from 'vite-plugin-tailwind-purgecss'

The plugin exports a named function, not a default export.

PurgeOptions

wrong

import { PurgeOptions } from 'vite-plugin-tailwind-purgecss'

correct

import type { PurgeOptions } from 'vite-plugin-tailwind-purgecss'

PurgeOptions is a TypeScript type; use type import for correct behavior.

require

wrong

const purgeCss = require('vite-plugin-tailwind-purgecss');

correct

const { purgeCss } = require('vite-plugin-tailwind-purgecss');

CommonJS require must destructure the named export; default require will not work.

Quickstart

Shows how to add the purgeCss plugin to a SvelteKit project with Vite configuration using TypeScript.

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig, type UserConfig } from 'vite';
import { purgeCss } from 'vite-plugin-tailwind-purgecss';

const config: UserConfig = {
	plugins: [sveltekit(), purgeCss()],
};

export default defineConfig(config);