Livewire 4 + Flux Yönetici Arayüzünü Bir Pakette Göndermek: Karşılaştığım Dört Problem

Bir Laravel paketinde admin UI oluşturmak, bir uygulamada oluşturmaktan oldukça farklıdır. Uygulamanın sunduğu avantajlar — derlenmiş bir Vite manifesti, kaydedilmiş bir düzen, kendi Livewire bileşenleriniz — burada yoktur. Bugün, laravel-config-webhook paketinde bir admin UI’nin render edilmesi, dört ayrı 500 hatasıyla yürütmek anlamına geliyordu. Her biri, bir paket ile ana uygulama arasındaki sınır hakkında küçük ancak keskin dersler içeriyor.

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

Bileşeni adlandırılmış bir isimle kaydettim ve çalıştırmada bir ComponentNotFoundException aldım. Sorunun kaynağı ince: Livewire 4 altında, :: içeren bir isim, tekil kayıtlı bileşenleri görmezden gelen bir isim alanı çözümü tetikler. Yani “güzel görünen” bir isim gizlice bulunamayan bir ara yüke yönlendirilir.

Çözüm, düz, nokta içeren bir isim kaydetmektir:

// ❌ düzgün görünüyor, ama "::" Livewire'ı bir isim alanı yoluna gönderir
Livewire::component('config-webhook::webhooks', Webhooks::class);

// ✅ dümdüz noktalı bir isim, tekil kayıtlı bileşene yönlendirilir
Livewire::component('config-webhook.webhooks', Webhooks::class);

Ders: bir paket içinde, bileşen adını bir tanımlayıcı olarak ele alın ve framework’ün ayırdığı karakterleri kullanmayın — :: sizin için kullanılmaz.

2. Flux ships Heroicons, not Pro/Lucide names

Flux’un ücretsiz katmanı Heroicons içerir. Pro-yalnızca veya Lucide stilinde bir isim çağırmaya çalışırsanız, bu çalıştırmada bir hata fırlatır. Ben webhook, ellipsis ve list kullandım; ücretsiz eşdeğerleri ise bolt, ellipsis-horizontal ve queue-listdir.

Bu, tam olarak bu yüzden şimdi, Blade’i okuyarak her simgeyi Flux’un mevcut stub dosyalarına karşı kontrol eden statik bir testle koruyorum. (Bu konu hakkında ayrı bir yazı yazılacak.) Flux ile bir paket UI gönderirken, sadece ücretsiz katman simgalarının varsayıldığını kabul edin, aksi takdirde Pro istemiyorsanız.

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

Paketin birleşik yedek düzeni, ana uygulamanın varlıklarını @vite ile yükleyordu. Yeni bir tüketici (veya paketin kendi çalışma alanı) içinde derlenmiş bir manifest yok, bu nedenle bir ViteManifestNotFoundException alırsınız. Bir paketin yedek düzeni kendi başına durmalıdır:

{{-- birleşik yedek düzen: kendi kendine yeterli, ana yapı aşaması yok --}}  @fluxAppearance

{{ $slot }}
@fluxScripts

Tailwind Play CDN + Flux direktifleri, UI’nin ana yapının oluşturmadan, kutudan çıkmasını sağlar. Ana uygulama her zaman gerçek şeyi istediğinde düzeni geçersiz kılabilir.

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

Bu durum, sinsi bir hatadır. Yapıda şu şekilde bir konfigürasyon vardı:

'ui' => [
    'layout' => 'components.layouts.app', // mantıklı bir varsayılan kullanım... 
],

…ve render config('config-webhook.ui.layout') ?: $bundledFallback ifadesini kullanıyordu. Varsayılanın null olmaması nedeniyle ?: asla yedekleme yapmadı — her zaman components.layouts.app'ya işaret ediyordu, bu yeni bir tüketicide mevcut değildir, dolayısıyla: 500. Varsayılan olarak null ayarlamak, yedeklemenin gerçekten işlev görmesini sağlar:

'ui' => [
    'layout' => null, // null → birleşik yedek kullanılır, host biri ayarlayana kadar
],

Ders: bir yedek sunarken ?: veya ?? kullanıyorsanız, tetikleyici varsayılanın boş değer olması gerektiğini, yoksa görünen bir değer olmadığını unutmayın.

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

Bu tür hatalar, hiçbir şeyin tam yolu yürütmemesi nedeniyle gizli kalır. Bu yüzden paketin Testbench çalışma alanını gerçekten bir webhook gönderecek şekilde bağladım: aktif bir abonelik tohumlayın, HMAC imzasını doğrulayan bir /receiver rotası ekleyin ve — önemli olarak — bu alıcı rotasından CSRF middleware'ini (PreventRequestForgery) hariç tutun, çünkü gelen bir webhook bir tarayıcı form gönderimi değildir:

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

Artık /fire ile migrate:fresh --seed komutundan sonra uçtan uca işlem yapılabiliyor. Tüm amacımız: gerçek yolu test etmek için çalışan bir demo sağlamak, bu dört sorunla karşılaşmaktan kaçınmanın en ucuz yolu.

The takeaway

Bu hataların her biri paket ↔ ana sınırda bulunuyor — framework'ün ayırdığı isimler, ana uygulamanın oluşturmadığı varlıklar, ana uygulamanın tanımlamadığı düzenler, gizlice kendi güvenlik ağınızı devre dışı bırakan varsayılan değerler. Bir paket içinde UI gönderdiğinizde, ana uygulamanın size hiçbir şey vermediğini varsayın, yedeği kendi başına yeterli hale getirin ve gerçek yolu uçtan uca değerlendiren bir çalışma alanı oluşturun.

Açık kaynak: github.com/cleaniquecoders/laravel-config-webhook.