Installation

CSS — add, don't replace

Append the import to your existing app.css (below your @import "tailwindcss"). The foundations layer on top of your own styles.

@import "tailwindcss";
/* …your existing styles… */
@import "./blatui.css";

JS — already running Alpine?

Don't import blatui.js (it would boot a second Alpine). Register BlatUI into your Alpine instance instead, before you start it:

import Alpine from 'alpinejs'
import { registerBlatUI } from './blatui-core.js'

registerBlatUI(Alpine)   // plugins + theme store + chart/calendar engines

window.Alpine = Alpine
Alpine.start()

JS — using Livewire or Flux?

Livewire bundles and starts Alpine for you, so don't npm install alpinejs (that's the duplicate-Alpine trap) and don't import blatui.js. Install only the plugins — npm install -D @alpinejs/anchor @alpinejs/collapse @alpinejs/focus (add apexcharts only if you use charts) — and register BlatUI onto Livewire's Alpine via the alpine:init hook:

import { registerBlatUI } from './blatui-core.js'

document.addEventListener('alpine:init', () => {
    registerBlatUI(window.Alpine)
})

BlatUI registers a theme store for dark mode. If Flux already drives dark mode, pass registerBlatUI(window.Alpine, { darkMode: false }) so the two don't both toggle .dark.

See what changed first

A dry run writes nothing. Add --diff for the full unified diff of every file that differs.

php artisan blatui:update --dry-run --diff

Then update

Without arguments it walks every installed family; pass names to scope it. Each differing file is confirmed individually.

php artisan blatui:update

# or just these, without prompting
php artisan blatui:update button card --force

Running a formatter over your views?

Pint or Prettier over resources/views rewrites the layout of every component you copied, so all of them read as changed. They're counted separately as same content, reformatted, and this leaves them out:

php artisan blatui:update --dry-run --ignore-whitespace

Compile the components with Blaze

Blaze compiles anonymous components into plain PHP functions. It works with or without Livewire. Every component in components/ui renders the same HTML under Blaze as under Blade, and the Livewire morph suite passes with it on. Rendering all of the docs examples takes about half as long.

composer require livewire/blaze:^1.0

use Livewire\Blaze\Blaze;

public function boot(): void
{
    Blaze::optimize()->in(resource_path('views/components/ui'));
}

Then run php artisan view:clear. Use the default compiler only: the fold and memo strategies bake a component's output in, and many BlatUI components read state at render time.

Memoize the tailwind-merge cache

Every $attributes->twMerge() looks its result up in your default cache store. On Redis that is a network round trip per component, over a thousand on a large page. A memoized store (Laravel 12.9+) answers repeats from memory for the rest of the request:

use Illuminate\Support\Facades\Cache;
use TailwindMerge\Contracts\TailwindMergeContract;
use TailwindMerge\TailwindMerge;

public function register(): void
{
    $this->app->singleton(TailwindMergeContract::class, fn () => TailwindMerge::factory()
        ->withConfiguration(config('tailwind-merge', []))
        ->withCache(Cache::memo())
        ->make());
}