Wireblade Laravel Package

Getting Started

Read the archived flag before anything else. The repo is archived and last tagged 2024-11-06 at v2.3.1. That does not stop it working — it's a Blade/Tailwind component library, so it has no runtime dependency on the maintainer — but it does change your plan: no upstream fixes, no Livewire 4 compatibility work, no security patches. Make the adoption decision deliberately, and assume you will own the source (fork it into your org's GitHub and point Composer at the fork) rather than treating it as a disposable dependency.

Confirm the stack window first. Check composer.json in the repo for the php, illuminate/*, and livewire/livewire constraints. Livewire is the highest-variance axis: a package written against Livewire 2 will load on Livewire 3 but components can break at the hydration layer. Also confirm the Tailwind major — the package is Tailwind-styled and its class names assume a specific Tailwind generation.

Install:

composer require lianmaymesi/wireblade:^2.3

Provider auto-discovery should register it; if not, add Lianmaymesi\Wireblade\WirebladeServiceProvider to bootstrap/providers.php.

The one step everyone forgets — tell Tailwind to scan the vendor views. This is the single most common cause of "the package is installed but everything renders unstyled":

// tailwind.config.js (Tailwind 3)
content: [
  './resources/**/*.blade.php',
  './vendor/lianmaymesi/wireblade/resources/views/**/*.blade.php',
],

/* app.css (Tailwind 4) */
@source "../../vendor/lianmaymesi/wireblade/resources/views";

If the package ships its own prebuilt CSS instead, publish assets and load them via the package's directive — check the README for which model it uses.

Where to look, in order:

1. README.md — the canonical component list and one working render example. This is your API surface.
2. The package's resources/views/components/ directory — every component, its props, and its slot structure, readable as plain Blade. Faster and more accurate than any docs.
3. config/wireblade.php after publishing — the author's intended knobs.
4. src/WirebladeServiceProvider.php — what's registered: component namespace, asset directives, view paths.
5. tests/ — the most reliable usage documentation for edge cases.

First use case: render one component in isolation on a scratch route and confirm it styles correctly before wiring it into a Livewire view:

{{-- routes/web.php: Route::view('/scratch', 'scratch'); --}}
<x-wireblade::button variant="primary">Hello</x-wireblade::button>

If it renders unstyled, the Tailwind content entry above is the fix 9 times out of 10. If it renders but the markup is wrong, clear compiled views first (php artisan view:clear) — stale compiled Blade is the classic false alarm on a fresh install.

Implementation Patterns

Build a thin in-house layer over the package, not on top of it. The archived status makes this non-negotiable. Wrap each component you use in your own Blade component so a future fork, replacement, or hand-roll is a one-file change. This costs an afternoon and buys you the ability to walk away.

{{-- resources/views/components/ui/button.blade.php --}}
@props(['variant' => 'primary', 'size' => 'md'])

<x-wireblade::button :variant="$variant" :size="$size" {{ $attributes }}>
    {{ $slot }}
</x-wireblade::button>

Call <x-ui.button> in app code. <x-wireblade::...> should appear only inside resources/views/components/ui/.

Forward $attributes and use the namespaced form. Always use <x-wireblade::button> rather than any globally registered shorthand — global aliases are collision-prone and shadow your own components silently. {{ $attributes }} on your wrapper keeps class, id, wire:model, and Alpine directives working without a bespoke prop for each.

Use the Plain Admin shell as the layout, not as a set of widgets. The package's value is the dashboard chrome — sidebar, topbar, cards, tables, modals. Adopt the layout structure wholesale in resources/views/layouts/app.blade.php and let Livewire full-page components render into its slot:

{{-- routes/web.php --}}
Route::get('/dashboard', Dashboard::class)->middleware('auth');

{{-- resources/views/layouts/app.blade.php --}}
<x-wireblade::layouts.app :title="$title ?? config('app.name')">
    {{ $slot }}
</x-wireblade::layouts.app>

Pair form components with Livewire wire:model and real-time validation. This is where the package earns its keep — the input/select/checkbox markup is already wired for wire:model, so you drop the attribute on and get reactivity for free:

<form wire:submit="save">
    <x-ui.input wire:model.live.debounce.400ms="search" label="Search" />
    @error('search') <p class="text-red-600 text-sm">{{ $message }}</p> @enderror

    <x-ui.button type="submit" wire:loading.attr="disabled">Save</x-ui.button>
</form>

Let Alpine handle client-only state; do not push it through Livewire. The package is styled to work alongside Alpine, so tab toggles, dropdowns, and sidebar collapse should be x-data/x-show with x-cloak, not Livewire properties. Reserve Livewire state for anything the server must know.

Theme and dark mode via Tailwind config, not per-component conditionals. If the package supports a dark variant, drive it with darkMode: 'class' on <html> and let the components' own dark: classes do the work. Never fork a component just to change a colour — override with a utility class at the call site (<x-ui.button class="!bg-red-600">) and keep the published views untouched for as long as possible.

Test the rendered output, not the package internals. Feature and Livewire tests should assert on selectors that come from your wrapper layer:

$this->get('/dashboard')->assertOk()->assertSee('ui-button');

Livewire::test(Dashboard::class)
    ->set('search', 'invoice')
    ->assertSee('Invoice #1024');

This keeps your test suite green if you ever swap the underlying component library.

Publish nothing until you need to change something. The published view path is a one-way copy — the moment you publish a view it becomes your code and the package will never update it again. Publish on demand, one file at a time, and record which files are pinned in the repo README.

Gotchas and Tips

Archived means you own the bugs. There will be no upstream fix for a Livewire hydration break or an accessibility issue. Before adopting, do a 30-minute audit: does every component you plan to use actually render correctly on your Laravel + Livewire + Tailwind versions? Test the ones you need, not the whole catalogue. Then fork the repo into your org's namespace so composer require yourco/wireblade is possible when you must patch it.

Tailwind purge is the #1 setup failure. Covered in Getting Started, repeated here because it is that common: styles work on the demo page and vanish in production, or work in npm run dev but not npm run build. The fix is the content/@source entry. If a specific class works in one place and not another, add it to the safelist — dynamic class construction (variant-$variant) is invisible to the scanner.

Asset base paths break after publishing. If you publish to public/vendor/wireblade/, check whether the package generates URLs with asset() (safe behind a subdirectory) or hard-codes /vendor/.... The usual symptom is styles loading in local dev on :8000 and 404ing behind a reverse proxy or on a subdomain path.

Alpine must load before the components hydrate. If dropdowns and tabs render open for a flash or not at all, it's a script-order problem: ensure Alpine is loaded once, with defer, before Livewire's scripts, and that no second copy arrives via the package. Use x-cloak with [x-cloak]{display:none} in your CSS to kill the flash.

Livewire version drift is the failure mode to recognise. Components render fine on first paint, then throw an opaque error on the first wire:model round-trip. That's a serialization/hydration mismatch, not a bug in your form. Pin Livewire in composer.json alongside this package and upgrade them together — you cannot rely on the archived package to declare a tight constraint.

Debug live components from the browser, not the log. wire:model problems rarely leave a useful stack trace. @dump($property) in the view, plus the network tab on the Livewire payload, resolves most of them — usually a stale wire:model on a property you renamed.

config:cache masks config changes. Editing config/wireblade.php in a cached environment does nothing until you re-cache. Run php artisan optimize:clear before concluding a config key is ignored, and php artisan view:clear before concluding a view override is ignored.

Class extension is a dead end here. No upstream maintainer means no compatibility work on constructor signatures. Prefer config → component props → published-view overrides → your own wrapper. If you must extend a package class, pin the exact version (2.3.1, not ^2.3) and add a test around the behaviour you extended.

Budget for the exit. Realistically, the day will come when Livewire 4 or Tailwind 4 leaves this package behind. Because your app calls <x-ui.*> exclusively, the exit is: rewrite resources/views/components/ui/ against a maintained alternative (TallStackUI, Mary UI, or hand-rolled) and delete the dependency. Keep that directory small — only the components you actually use — and the migration stays measured in hours, not weeks.