vite-plugin-purgecss-updated-v5

1.2.7 verified Mon Apr 27 auth: no javascript

Vite plugin that integrates PurgeCSS to remove unused CSS from production bundles. Version 1.2.7 supports Vite 3 through 8 as peer dependencies, making it future-proof for Vite 5+ projects. TypeScript types included. Key differentiators: automatic detection of CSS modules hashed class names, supports PurgeCSS variables option, and passes Vite chunks as content automatically, reducing configuration overhead.

Common errors

error Error: Cannot find module 'vite-plugin-purgecss-updated-v5' ↓

cause Package not installed or incorrect import path.

fix

Run: npm install --save-dev vite-plugin-purgecss-updated-v5

error TypeError: pluginPurgeCss is not a function ↓

cause Using CommonJS require() instead of ESM import.

fix

Use: import pluginPurgeCss from 'vite-plugin-purgecss-updated-v5'

error ERROR: Unused CSS - expected classes removed ↓

cause PurgeCSS removed classes that are dynamically added, e.g., via JavaScript.

fix

Add safelist options to preserve those classes: safelist: { standard: ['dynamic-class'] }

Warnings

gotcha The `content` and `css` options bypass Vite's build pipeline. Do not pass files requiring Vite processing (e.g., .vue, .svelte) to these options. ↓

fix Use the default automatic content detection; only provide raw strings or already-processed file paths.

deprecated Package name differs from original '@mojojoejo/vite-plugin-purgecss' which may cause confusion. Ensure correct import path. ↓

fix Use 'vite-plugin-purgecss-updated-v5' as shown in documentation.

breaking Plugin expects Vite 5+ but also supports older versions as peer (3, 4). Incorrect peer resolution may cause silent failures. ↓

fix Check your Vite version and ensure it matches the peer range: '^3 || ^4 || ^5 || ^6 || ^7 || ^8'.

gotcha CSS Modules are automatically supported via postcss-modules, but custom extractors may interfere with hashed class name detection. ↓

fix Avoid overriding `defaultExtractor` when using CSS Modules; use the built-in handling instead.

Install

npm install vite-plugin-purgecss-updated-v5

yarn add vite-plugin-purgecss-updated-v5

pnpm add vite-plugin-purgecss-updated-v5

Imports

default export (pluginPurgeCss)
wrong
```
const pluginPurgeCss = require('vite-plugin-purgecss-updated-v5')
```
correct
```
import pluginPurgeCss from 'vite-plugin-purgecss-updated-v5'
```
Package is ESM-only; named exports may not be available. Default import is the plugin function.

Options type

import type { UserDefinedOptions } from 'vite-plugin-purgecss-updated-v5'

Type import for PurgeCSS options, available since v1.0.0

Plugin registration
wrong
```
plugins: [pluginPurgeCss({ variables: 'true' })]
```
correct
```
plugins: [pluginPurgeCss({ variables: true })]
```
Options object is passed directly; variables is a boolean, not a string.

Quickstart

Sets up PurgeCSS with Vite, safelisting elements and regex patterns, enabling variable purging, and disabling font-face/keyframe removal.

// vite.config.ts
import { defineConfig } from 'vite';
import pluginPurgeCss from 'vite-plugin-purgecss-updated-v5';

export default defineConfig({
  plugins: [
    pluginPurgeCss({
      safelist: {
        standard: ['body', 'html'],
        deep: [/^my-/],
        greedy: [/^my-/],
      },
      variables: true,
      fontFace: false,
      keyframes: false,
    }),
  ],
});