DEV Community

Cover image for Shipping a Livewire 4 + Flux admin UI inside a package: four gotchas that 500'd on me
Nasrul Hazim Bin Mohamad
Nasrul Hazim Bin Mohamad

Posted on

Shipping a Livewire 4 + Flux admin UI inside a package: four gotchas that 500'd on me

#laravel #php #livewire #opensource

Bundling an admin UI inside a Laravel package is a different game from building one in an app. The app's conveniences — a compiled Vite manifest, a registered layout, your own Livewire components — aren't there. Today, getting the bundled admin UI in laravel-config-webhook to actually render meant walking through four separate 500s. Each one is a small, sharp lesson about the boundary between a package and its host app.

1. A Livewire 4 component name can't contain ::

I registered the component with a namespaced-looking name and got a ComponentNotFoundException at runtime. The cause is subtle: under Livewire 4, a name containing :: triggers namespace resolution that ignores singly-registered components. So a "nice looking" name silently routes to a lookup that will never find it.

The fix is to register a plain, dotted name:

// ❌ looks tidy, but the "::" sends Livewire down a namespace path
Livewire::component('config-webhook::webhooks', Webhooks::class);

// ✅ a flat dotted name resolves to the singly-registered component
Livewire::component('config-webhook.webhooks', Webhooks::class);
Enter fullscreen mode Exit fullscreen mode

Lesson: in a package, treat the component name as an identifier with framework-reserved characters — :: is not yours to use.

2. Flux ships Heroicons, not Pro/Lucide names

The free tier of Flux ships Heroicons. Reach for a Pro-only or Lucide-style name and it throws at runtime. I'd used webhook, ellipsis, and list; the free equivalents are bolt, ellipsis-horizontal, and queue-list.

This is the same trap that bit my SSO package — which is exactly why I now guard it with a static test that reads the Blade and checks every icon against Flux's actual stub files. (Separate post on that.) If you ship a package UI with Flux, assume free-tier icons only unless you require Pro.

3. Don't @vite host assets that don't exist

The bundled fallback layout @vite-d the host app's assets. In a fresh consumer (or the package's own workbench) there's no compiled manifest, so you get a ViteManifestNotFoundException. A package's fallback layout has to stand on its own:

{{-- bundled fallback layout: self-contained, no host build step --}}
<head>
    <script src="https://cdn.tailwindcss.com"></script>
    @fluxAppearance
</head>
<body>
    {{ $slot }}
    @fluxScripts
</body>
Enter fullscreen mode Exit fullscreen mode

Tailwind Play CDN + Flux directives mean the UI renders out of the box, with zero assumptions about the host's build pipeline. The host can always override the layout when it wants the real thing.

4. A non-null layout default defeats your own fallback

This one is sneaky. The config had:

'ui' => [
    'layout' => 'components.layouts.app', // a sensible-looking default…
],
Enter fullscreen mode Exit fullscreen mode

…and the render used config('config-webhook.ui.layout') ?: $bundledFallback. Because the default was non-null, the ?: never fell back — it always pointed at components.layouts.app, which doesn't exist in a bare consumer, so: 500. Defaulting to null lets the fallback actually do its job:

'ui' => [
    'layout' => null, // null → the bundled fallback is used unless the host sets one
],
Enter fullscreen mode Exit fullscreen mode

Lesson: when you offer a fallback via ?: or ??, the default that triggers it must be the empty value, not a placeholder that looks like a value.

Bonus: prove it end-to-end in the workbench

Bugs like these hide because nothing exercises the full path. So I wired the package's Testbench workbench to deliver a webhook for real: seed an active subscriber, add a /receiver route that verifies the HMAC signature, and — importantly — exclude the CSRF middleware (PreventRequestForgery) from that receiver route, since an inbound webhook isn't a browser form post:

Route::post('/receiver', VerifyAndStore::class)
    ->withoutMiddleware(PreventRequestForgery::class);
Enter fullscreen mode Exit fullscreen mode

Now /fire delivers end-to-end straight after migrate:fresh --seed. The whole point: a demo that actually runs the real path is the cheapest way to keep these four gotchas from coming back.

The takeaway

Every one of these bugs lives at the package ↔ host boundary — names the framework reserves, assets the host may not have built, layouts the host may not define, defaults that quietly disable your own safety net. When you ship UI inside a package, assume the host gives you nothing, make the fallback self-sufficient, and wire a workbench that exercises the real path end-to-end.

Open source: github.com/cleaniquecoders/laravel-config-webhook.

Top comments (0)