How to use PurgeCSS with Laravel, Vite and Bootstrap 5

There's this really cool bit of software called PurgeCSS and what it does is looks through pages on your site and works out all the CSS you're not using and then gives you back a slimmed down version. Now with Laravel, Vite and Tailwind you get this setup for free, already configured an ready to go - very nice!

However what if you don't want to use Tailwind CSS to style your website? You might be a hardcore Bootstrap fan, a bit like I am. What if you've bought a theme / template and you get this massive, bloated styles.css file which has all the bells and whistles, but you only need a fraction of it? This post is for you!

For ages I just didn't understand how to get this particular setup to work. However it turns out it's very simple and works a treat. Also one of the best things about this is that it doesn't intefere with Tailwind in any way, If you want to use Bootstrap for your marketing pages, but you also want to use Laravel Breeze or Jetstream for your auth (whose default styling is Tailwind) this works great, you can have best of both worlds!

Plugins Needed

You only need one plugin - @erbelion/vite-plugin-laravel-purgecss head over to the github link and do an npm install.

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

How to configure PurgeCSS with Laravel, Vite and Bootstrap

After you've installed the plugin, head over to your vite.config.js file in the root of your Laravel installation. You'll need to import the plugin and include a few options to get PurgeCSS plumbed in.

import {defineConfig} from 'vite';
import laravel from 'laravel-vite-plugin';
import purge from '@erbelion/vite-plugin-laravel-purgecss'

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/js/app.js',
                'public/css/styles.css',
            ],
            refresh: true,
        }),
        purge({
            templates: ['blade'],
            paths: ['resources/views/*'],
            safelist: ['tooltip', 'tooltip-arrow', 'bs-tooltip-auto', 'tooltip-inner']
        })
    ],
});

So as you can see I've got the import purge from '@erbelion/vite-plugin-laravel-purgecss' at the top underneath the standard laravel vite plugins.

Next, under the laravel / input array you've got the list of files (CSS and JS) that you want to be compiled. What I've done here is create a css folder in my public folder (public/css/styles.css) and this is where my mega bloated bootstrap file lives. I've called mine styles.css. This where you'd add the path to your CSS or JS files, you can add many CSS files here, you're not just limited to the one.

Moving on, we have a new purge() function. I've got mine setup to only read blade files and it will check my resources/views/* folder for any blade files inside of it. This should cover your basic Laravel setup.

I've also added a safelist, which is just an array of classes you want PurgeCSS to ignore. I found that Bootstrap tooltips lost a bit of styling, so adding the classes back in worked a treat.

Compiling your assets

To get your slimmed down CSS file you'll need to run the following command: npm run build this will create your production assets. Note you won't get the slimmed down file if you run npm run dev.

Head over to your HTML template and add / update your code to pull in the compiled assets.

<head>
    <meta charset="UTF-8">
    <meta name="viewport"
          content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Document</title>
    @vite(['public/css/styles.css'])
</head>

As you can see, I've added the path where my full, bloated CSS file lives. Vite is clever enough to swap your assets out for their compiled versions depending on what npm run dev / build command you run. Since this is an array, if you have more css files you need to load it, just add them to the array.

The compiled files live in your public/build/assets folder which should get automatically created when you run npm run build.

The results!

So before I used PurgeCSS, my CSS file was weighing in at a massive 507.87kb which is half a megabyte. Totally unacceptable to force someone to have to load that file in. I can actually see the page jumping about and taking time to load up all the styles. Awful experience.

After compiling my production assets, I get a lovely, svelte 42.60kb styles.css file, which shaved off a massive 465kb! The page loads up almost instantly now and no elements jumping about on screen.

So there you have it. PurgeCSS with Laravel, Vite and Bootstrap 5. Nowhere near difficult as I thought it would be. I hope this helps a lot of people out.

If you're feeling generous give the github repo a star. Thanks for reading.


More Posts