vite-plugin-laravel-purgecss

A Vite plugin that integrates PurgeCSS with Laravel 9-13 template assets (currently updated up to laravel/[email protected]).

This plugin purges unused CSS assets only in production mode (pnpm build / yarn build / npm run build).

📦 Installation

Using pnpm:

pnpm add -D @erbelion/vite-plugin-laravel-purgecss

Using yarn:

yarn add -D @erbelion/vite-plugin-laravel-purgecss

Using npm:

npm i -D @erbelion/vite-plugin-laravel-purgecss

🚀 Usage

To use the plugin in your Vite configuration (vite.config.ts):

import purge from '@erbelion/vite-plugin-laravel-purgecss'

export default {
    plugins: [
        laravel(...),
        purge()
    ]
}

See more examples

🛠️ Options

| Parameter | Type | Optional | Description | | ---------------- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | paths | string[] | Yes | List of paths to be processed by PurgeCSS. | | rehash | boolean | Yes | Determines whether to hash asset filenames after purging. | | PurgeCSS Options | Partial<UserDefinedOptions> | Yes | PurgeCSS options (see docs). | | templates | string[] | Yes | ❌ Deprecated (see anyway). |

paths Option

If the paths option isn't specified, it will default to:

resources/{js,views}/**/*.{blade.php,svelte,vue,html}

rehash Option (experimental)

If the rehash option isn't specified, it will default to false.

⚠️ Experimental — rehash patches manifest.json on disk after Vite writes it. This relies on assumptions about Vite's output format that may break across Vite versions.

Why does rehash exist?

Vite hashes CSS filenames based on the unprocessed SCSS/CSS source at build time (e.g. app-B2qGsMUw.css). That hash does not change when you add a new class to a Blade template — even though PurgeCSS will now include additional rules in the output.

Without rehash, a browser or CDN that cached the old CSS file would never know to re-fetch it, because the filename is identical despite different content.

With rehash enabled, the plugin appends an additional hash derived from the purged CSS content (e.g. app-B2qGsMUw-e5ec2996.css) and patches manifest.json accordingly.

All Options

type Options = {
    // Plugin options
    paths?: string[] // Defaults to `resources/{js,views}/**/*.{blade.php,svelte,vue,html}`
    rehash?: boolean // Defaults to `true`
    templates?: string[] // ❌ Deprecated

    // PurgeCSS options
    defaultExtractor?: ExtractorFunction
    extractors?: Array<Extractors>
    fontFace?: boolean
    keyframes?: boolean
    output?: string
    rejected?: boolean
    rejectedCss?: boolean
    stdin?: boolean
    stdout?: boolean
    variables?: boolean
    safelist?: UserDefinedSafelist
    blocklist?: StringRegExpArray
}

💡 Other Examples

Via custom path:

purge({
    paths: ["resources/{js,views}/**/*.{blade.php,svelte,vue,html}"],
})

Via custom paths + safe list styling: (always keep #bruh, .nice-button, and h1 styling)

purge({
    paths: ["resources/views/**/*.blade.php", "resources/{js,views}/**/*.vue"],
    safelist: ["bruh", "nice-button", "h1"],
})

Example config with fix for escaped prefixes (sm:, lg:, etc.):

purge({
    extractors: [
        {
            extractor: (content) => {
                return content.match(/[a-z-_:\/]+/g) || []
            },
            extensions: ["php", "vue", "html"],
        },
    ],
})

📚 Tutorial

https://github.com/erbelion/tutorial-vite-plugin-laravel-purgecss

👉 See Also

• vite-plugin-sveltekit-purgecss