Registry / devops / vite-plugin-tailwind-purgecss

vite-plugin-tailwind-purgecss

library0.3.5jsnpmunverified

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.

devops

npm install vite-plugin-tailwind-purgecss

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-TAILWI

vite-plugin-tailwind-purgecss

devopsjavascriptv0.3.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

purgeCss

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

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

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

PurgeOptions

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

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

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

require

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

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

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

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);

Debug

Known issues

breakingv0.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 }).

affects: >=0.3.0

breakingv0.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.

affects: >=0.3.0

breakingv0.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 }.

affects: >=0.3.0

gotchaThe 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.

affects: >=0.3.0

deprecatedThe 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.

affects: >=0

Errors

Common errors & fixes

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

Missing tailwindcss peer dependency when using v0.3.0+.

fix

Install tailwindcss: npm install -D tailwindcss@^3.3.0

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

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

fix

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

Error: purgeCss is not a function

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'`.

Upgrade

Version history

0.3.5latest on npm

Audit

Dependencies

tailwindcssrequiredRequired as peer dependency to detect and purge Tailwind classes.

viterequiredRequired as peer dependency; plugin works with Vite 4, 5, or 6.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/AdrianGonz97/vite-plugin-tailwind-purgecss ↗

packagehttps://www.npmjs.com/package/vite-plugin-tailwind-purgecss ↗