Integrating UnoCSS with Laravel and Vite

Integrating UnoCSS with Laravel and Vite offers a streamlined way to enhance your development workflow by combining the power of atomic CSS, Laravel’s robust backend, and Vite’s fast build tool. This guide will walk you through setting up UnoCSS with Laravel and Vite, leveraging insights from a helpful blog post found at Moussa Clarke’s Code Blog. This setup ensures that you can utilize UnoCSS’s atomic CSS capabilities within Laravel’s blade templates efficiently.

1. Configuring UnoCSS

First, you need to create a configuration file for UnoCSS. This file tells UnoCSS how to process your CSS according to your project’s needs.

uno.config.js:

import { defineConfig } from 'unocss';
import { presetAttributify, presetUno } from 'unocss';

export default defineConfig({
    presets: [presetUno(), presetAttributify()],
    postcss: true,
    cli: {
        entry: {
            patterns: ['resources/views/**/*.blade.php'],
            outFile: 'resources/css/uno.css',
        },
    },
});

2. Updating Vite Configuration

Next, update your Vite configuration to include the UnoCSS plugin and a custom pre-build step. This step is crucial for ensuring UnoCSS processes your CSS files before Vite compiles the project.

vite.config.js:

import laravel from 'laravel-vite-plugin';
import { execSync } from 'child_process';
import UnoCSS from 'unocss/vite';

// ...
plugins: [
    {
        name: 'pre-build-example',
        buildStart() {
            execSync('npx unocss');
        },
    },
    UnoCSS({
        configFile: 'uno.config.js',
    }),
    //...other stuff
]

The custom plugin 'pre-build-example' uses execSync('npx unocss') to ensure UnoCSS processes your CSS files using the configuration specified in uno.config.js before Vite’s build process begins.

3. Importing UnoCSS in Your CSS/SASS

Lastly, to use the UnoCSS styles in your application, you’ll need to import the generated CSS file into your main CSS or SASS file.

@import "./uno.css";

By following these steps, you successfully integrate UnoCSS with Laravel and Vite, allowing you to enjoy the benefits of atomic CSS in your Laravel projects with Vite’s build optimizations. This setup ensures your styles are processed and ready to be utilized in your blade templates, enhancing your development efficiency and project performance.

Edit: found a better way

After a few days trying to implement a better workflow with UnoCss, I discovered that there were two other ways far more effective than previously noted. These are the discoveries:

Preferred way

1- Use the external config file as previously stated.

Your config should look like this:

import { defineConfig } from 'unocss';
import { presetAttributify, presetUno } from 'unocss';

export default defineConfig({
    presets: [presetUno(), presetAttributify()],
    postcss: true,
    transformCSS: 'pre',
    cli: {
        entry: {
            patterns: ['resources/views/**/*.blade.php'],
            outFile: 'resources/css/uno.css',
        },
    }
});

notice that there is a ‘cli’ statement, but it will only be used as a backup (used in the second method)

2- the vite.config would look like this:

/... some code
UnoCSS({
            configFile: 'uno.config.js',
        }),

3- set the Lavare plugin to reload ‘true’

laravel({
            input: ['resources/js/app.js', 'resources/sass/app.scss'],
            refresh: true,
        }),

That should do it. and notice that there is a config not mentioned in the cssuno plugin, the ‘transformCSS’ which is the one responsible to make it work nicely with the rest of the Laravel setup.

In case that does not work in your setup, fallback to the next step:

the fallback

1- set the laravel ‘refresh’ to false

2- add this plugin as the last plugin of the array:

{
            name: 'blade',
            handleHotUpdate: {
                handler: ({ file, server }) => {
                    if (file.endsWith('.blade.php')) {
                        execSync('npx unocss');
                        setTimeout(() => {
                            server.hot.send({
                                type: 'full-reload',
                                path: '*',
                            });
                        }, 500);
                    }
                },
            },
        },

Is not the most optimal flow, but it does help to overcome other limitations.

Hope that helps!