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);
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>
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…
],
…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
],
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);
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.