Řešení potíží

Běžné problémy a jejich nápravy. Většina jsou nesoulady konfigurace v hostitelské Laravel aplikaci, ne bugy ve Wire.

Tlačítka a inputy jsou neviditelné

Příznak: Tlačítka, badge a focus ringy se vykreslí jako bílé-na-průhledném nebo zmizí úplně.

Příčina: Tailwind barva primary není definovaná. Wire používá primary pro každý akcent, takže bez ní tyto prvky nemají barvu.

Náprava: Definujte primary v konfiguraci Tailwindu — viz Začínáme → Barva primary a Vzhled → Barvy.

Komponenty se vykreslují bez stylů

Příznak: Markup se objeví, ale bez Tailwind stylování.

Příčina: Tailwind neskenuje vendor pohledy Wire, takže se jejich třídy odstraní z buildu.

Náprava: Přidejte cesty k pohledům Wire do pole content v Tailwindu:

content: [
    './vendor/nyoncode/wire-core/resources/views/**/*.blade.php',
    './vendor/nyoncode/wire-core/src/**/*.php',
    './vendor/nyoncode/wire-forms/resources/views/**/*.blade.php',
    './vendor/nyoncode/wire-forms/src/**/*.php',
    './vendor/nyoncode/wire-table/resources/views/**/*.blade.php',
    './vendor/nyoncode/wire-table/src/**/*.php',
    './vendor/nyoncode/wire-sortable/resources/views/**/*.blade.php',
    './vendor/nyoncode/wire-sortable/src/**/*.php',
],

Cesty src/**/*.php jsou důležité: některé komponenty skládají své utility třídy v PHP (pozicování, šířka, výška), takže skenování jen Blade pohledů nechá tyto třídy odstraněné. Na Tailwindu 4 přidejte odpovídající @source řádky pro resources/views i src (viz průvodce začínáme).

Poté přebuildujte assety (npm run build nebo npm run dev).

Slide-over je ukotvený vlevo, přetéká nebo nejde scrollovat

Příznak: Slide-over akce (->slideOver()) se objeví přišpendlený vlevo se ztmavenou stránkou vpravo, jeho obsah přetéká za viewport, patička sedí mimo obrazovku dole a tělo nejde scrollovat.

Příčina: Slide-over skládá své utility pro pozicování, šířku a výšku v PHP (SlideOverComponent), ne v Blade souboru — třídy jako sm:right-0, sm:pl-10, sm:h-full, max-h-[85vh] a sm:max-w-2xl. Pokud Tailwind skenuje jen resources/views a ne src balíčku, tyto třídy se odstraní: bez sm:right-0 panel spadne vlevo a bez výškových utilit není nikdy omezený na výšku, takže přetéká místo scrollování těla.

Náprava: Přidejte cesty src/**/*.php (Tailwind 3) nebo odpovídající @source řádky (Tailwind 4) podle Komponenty se vykreslují bez stylů, pak přebuildujte. Viz také průvodce začínáme.

„No publishable resources for tag“

Příznak: vendor:publish hlásí žádné zdroje pro tag jako wire-forms-config.

Příčina: Publish tagy Wire používají oddělovač ::, ne pomlčku.

Náprava: Použijte správný formát tagu:

php artisan vendor:publish --tag=wire-forms::config   # ✅
php artisan vendor:publish --tag=wire-forms::views
php artisan vendor:publish --tag=wire-forms::translations

Skupiny jsou config, views, translations a (kde je to relevantní) migrations — každá s prefixem krátkého názvu balíčku a ::.

Chyby Alpine nebo komponenty reagující dvakrát

Příznak: Chyby v konzoli o dvojité inicializaci Alpine, nebo direktivy spouštějící se dvakrát.

Příčina: Alpine byl nainstalován a nastartován samostatně. Livewire 4 už Alpine dodává a startuje.

Náprava: Odstraňte jakoukoli samostatnou instalaci Alpine a volání Alpine.start(). Nechte ho poskytnout Livewire.

Vnořená tabulka ukazuje řádky vnější tabulky

Příznak: Na stránce, jejíž komponenta má tabulku a zároveň obsahuje další Livewire komponentu s vlastní tabulkou (zakázka s dodacími listy v záložce), řazení ani změna počtu na stránku vnější tabulkou nepohne, zato vnořená tabulka najednou vypisuje řádky té vnější. V konzoli je isSelected is not defined a podobné.

Příčina: Livewire 4 aplikuje fragment islandu tak, že v DOM komponenty hledá značku s tokenem fragmentu — a u vnořené komponenty se nezastaví. Token pojmenovává zkompilovaný view islandu, takže ho sdílí každá tabulka na stránce (data-region, action-modals), a fragment vnější tabulky dopadne do vnitřní. Platí pro všechny verze Livewire 4.x do 4.4.6 (oprava navržena v livewire/livewire#10737).

Řešení: Nechte v layoutu @wireStackScripts — wire-core 2.1.1 po dobu každé zprávy skryje značky vnořených komponent, takže fragment může dopadnout jen do své komponenty. Layout bez bundlu wire-core obcházku nedostane.

Ovládací prvek tabulky s pollingem se sám vrátí

Příznak: Na tabulce s poll() nebo live() občas změna počtu na stránku nebo klik na řazení nic neudělá: výběr skočí na původní hodnotu a řádky zůstanou, jak byly. Napodruhé to projde. Stejně může přijít vniveč otevřený modal nebo uložená buňka.

Příčina: Řádky a modaly tabulky jsou islandy Livewiru; poll, vyhledávání a filtry ne. Livewire 4 koordinuje souběžné požadavky jen v rámci jednoho scope, takže akce z islandu vyslaná během tiku pollingu odejde vedle něj se stejným snapshotem — a podle dokumentace islandů „the last response to return will win the state battle". Když poslední doběhne tik, jeho starší snapshot změnu přepíše.

Řešení: Nechte v layoutu @wireStackScripts. Od wire-core 2.2.3 tabulka vykresluje data-wire-islands="shared-state" a wire-core na islandy a kořen té komponenty uplatní pravidla, která Livewire drží v jednom scope: tik, který přijde, když běží něco jiného, zahodí, běžící tik kvůli akci uživatele zruší a cokoli jiného nechá počkat, než druhý požadavek doběhne. Pohled tabulky publikovaný před 2.2.3 značku nemá — publikujte ho znovu (--tag=wire-table::views --force). Vlastní komponenta s islandy nad sdíleným stavem se může přihlásit stejným atributem na elementu, který jí patří.

wireX is not defined po návštěvě přes wire:navigate

Příznak: Stránka funguje, když se načte přímo, ale při příchodu přes wire:navigate — nebo tlačítky Zpět/Vpřed v prohlížeči — je tabulka či formulář mrtvý. V konzoli je ReferenceError se jménem Wire komponenty (wireRecordSelection, wireDropdown, wireSortable, …). Nejhlasitější varianta je šedý scrim přes celou stránku nad mrtvou tabulkou: každý backdrop mobilního sheetu je navázaný na stav, který nikdy nevznikl.

Příčina: Bundle definující komponentu dorazil spolu s novou stránkou a cesta cachovaného Zpět/Vpřed v Livewire nečeká na nově injektované <head> skripty, než na prohozeném markupu inicializuje Alpine.

Náprava: Dejte direktivu do <head> layoutu, ať jsou controllery v dokumentu už od prvního načtení stránky, kde je nemá co předběhnout:

<head>
    @wireStackScripts
</head>

Viz Začínáme → JavaScriptové assety.

JavaScriptové 404 a wireX is not defined

Příznak: Tentýž ReferenceError jako v předchozí sekci, ale na každé stránce a bez ohledu na to, jak jste se na ni dostali — objeví se i po tvrdém reloadu. V network tabu jsou 404 na /wire-core/assets/dropdown.js, /wire-table/assets/records.js nebo sourozence pod /wire-forms/… či /wire-sortable/….

Příčina: Sešly se dvě věci. Balíčky si normálně bundly zkopírují do public/vendor/<balíček> a emitují tyhle cesty, takže PHP nic neřeší — URL /wire-core/assets/… ve vašem markupu znamená, že se kopie nepovedla a zaskakuje za ni routa balíčku. A váš webserver na tu routu odpovídá sám, místo aby ji předal PHP. Standardní nginx konfigurace Laravelu posílá cokoliv, co není na disku, do index.php, konfigurace s blokem pro statické assety už ne:

location ~* \.(js|css)$ {
    try_files $uri =404;      # routa není soubor na disku → 404, PHP to nikdy neuvidí
}

Nic z toho není specifické pro tyhle balíčky: tentýž blok vrací 404 i na Livewire vlastní /livewire-{hash}/livewire.js.

Řešení — zapisovatelné public/, nebo kopie při buildu. Obvyklou příčinou je public/, do kterého webový uživatel nesmí zapisovat, nebo read-only kontejner. Buď zápis povolte, nebo kopii udělejte, dokud je filesystém ještě zapisovatelný:

php artisan vendor:publish --tag=laravel-assets --force

Nebo zpřístupněte routu tím, že necháte blok propadnout do front controlleru — správná odpověď tam, kde zapisovatelné public/ opravdu není ve hře:

location ~* \.(js|css)$ {
    try_files $uri /index.php?$query_string;   // [tl! focus]
}

Příbuzné varování, když kopie existují, ale po upgradu je nešlo obnovit:

wireStack: the published copies of wire-core/dropdown are older than the bundles
the packages ship, and are what this page just loaded.

Stránka funguje dál — starý bundle je lepší než žádný — ale stojí za tím tentýž problém se zápisem. Viz Začínáme → JavaScriptové assety.

Řazení přestalo fungovat, nebo můj kód přišel o window.Sortable

Příznak: Po upgradu vyhazuje vlastní JavaScript vaší aplikace Sortable is not defined.

Příčina: SortableJS je nově zkompilovaný do bundlu wire-sortable a config('wire-sortable.sortablejs_cdn') je ve výchozím stavu null — CDN skript, který po sobě nechával globál, se tedy už nenačítá. Vlastního řazení Wire se to netýká; drag controller používá zabundlovanou kopii.

Náprava: Pokud váš kód globál potřebuje, řekněte si o něj — buď nastavte konfigurační klíč zpět na CDN URL, nebo si dejte npm install sortablejs a window.Sortable přiřaďte sami. Viz Instalace Sortable → SortableJS.

JavaScript pole neběží uvnitř modalu

Příznak: JS-based pole funguje na normální stránce, ale je mrtvé při otevření v modalu nebo po Livewire updatu.

Příčina: Prostý <script> tag injektovaný přes DOM morphing Livewire se nikdy nespustí.

Náprava: Načtěte skript pomocí direktivy @assets Livewire (vestavěný TiptapEditor to dělá). Pokud stavíte vlastní JS pole, následujte stejný vzor — viz Rozšíření formulářů → JS-based pole.

save() vyhodí chybu bez modelu

Příznak: Volání $form->save() vyhodí chybu.

Příčina: Formulář nemá model (model(null) nebo žádný nastavený), takže není co uložit.

Náprava: Buď nastavte model (->model(User::class) pro create, ->model($user) pro update), poskytněte vlastní perzistenci pomocí ->using(...), nebo místo toho zavolejte ->validate(), když potřebujete jen data. Viz Režimy modelu.

Notifikace / toasty se neobjevují

Příznak: Akce uspějí, ale žádný toast ani notifikace se nezobrazí.

Příčina: V layoutu chybí kontejner notifikací.

Náprava: Přidejte ho jednou blízko konce <body>:

<x-wire-notifications::toast-container />

Layout viz Začínáme a Core → Notifikace.

Validační chyby se nezobrazují

Příznak: Validace selže (uložení je zablokováno), ale pod polem se nevykreslí žádná zpráva.

Příčina: statePath formuláře neodpovídá vlastnosti komponenty držící stav, takže se klíče chyb a cesty polí rozcházejí.

Náprava: Ujistěte se, že ->statePath('data') odpovídá veřejné vlastnosti (public array $data = []) a že formulář vykreslujete pomocí {{ $this->form }}. Chyby polí jsou klíčované plnou state cestou (například data.email) — na tuto cestu asertujte v testech.

Průvodce se nikdy neobjeví

Příznak: Průvodce je zaregistrovaný a žádná prohlídka se nespustí.

Příčiny v pořadí, v jakém je stojí za to projít — průvodce, který neběží, je vždycky tichý, protože každá z těchto věcí je něco, co legitimně rozhodnout může:

1. Dotyčný ho už viděl. Počítá se dokončení i přeskočení a záznam se drží pro aktuální hodnotu since(). Při vývoji na to narazíte hned po prvním načtení stránky. Použijte Spustit průvodce znovu v uživatelském menu, nebo si po dobu práce na něm nastavte WIRE_TOURS_DRIVER=null v .env, což ho spustí při každém načtení stránky.
2. Odložil si ho. Průvodce s welcome blokem jde odbýt tlačítkem „Odložit“, což ho umlčí do konce dané session — a to „Odložit“, které vyčerpá povolený počet z postpone(), ho zaznamená jako viděný natrvalo, přesně jako přeskočení. Nové přihlášení nebo driver null to smaže.
3. Nikdo ho nekreslí. Panel se vykresluje přes PageChrome, který vykresluje layout wire-admin. Vlastní layout musí vykreslit stejné dvě smyčky — viz Tour → Vlastní layout. @wireStackScripts musí být také v <head>, protože panel umisťují controllery, které doručuje.
4. Prvky všech kroků chybí nebo jsou skryté. Krok, jehož prvek na stránce není, nebo je vykreslený, ale nemá rozměr (zavřený dropdown, bulk lišta před výběrem řádků), se záměrně přeskakuje — a průvodce, který takhle přijde o všechny kroky, se nespustí. Porovnejte jména se stránkou v devtools; viz Vzhled → Jak jméno najít.
5. Obrazovka neodpovídá. zones(), resource() a page() se skládají přes AND. zones('sales') nikdy neodpovídá aplikaci bez zón — aplikaci bez zóny jmenuje zones(null).
6. Autorizace ho zamítá. permission(), authorize() a authorizeUsing() selhávají zavřeně a průvodce s oprávněním se nikdy neukáže hostovi.
7. Obrazovku si první nárokoval jiný průvodce. Na jednu návštěvu běží jen jeden; vyhrává nejnižší sort() a ostatní čekají na další návštěvu.

Náprava: projděte ten seznam proti Tour → Jak to funguje. Když chcete ověřit zapojení, aniž byste se dotkli omezení, zaregistrujte průvodce úplně bez omezení a s jedním krokem na admin-sidebar: pokud se nespustí ani ten, je příčina v bodě (1), (2) nebo (3).

Upravený průvodce se nespustí znovu

Příznak: Kroky nebo znění se změnily, nasazení proběhlo, a lidé, kteří průvodce už dokončili, pořád nevidí nic.

Příčina: Obsah průvodce se nijak nehashuje a nic nečte verzi balíčku. K člověku se ukládá hodnota since() daného průvodce a porovnává se na nerovnost — takže upravený průvodce, kterému se since() nepohnulo, je pořád potvrzený.

Náprava: změňte since() na cokoli jiného — číslo vydání, datum, slovo:

Tour::make('getting-started')->since('2.2')->steps([...]);

Každý, kdo dokončil starou verzi, uvidí novou jednou. Nikdo ji neuvidí dvakrát a není tu úložiště, které by se mazalo, ani příkaz, který by se pouštěl. Přejmenování id průvodce má navenek stejný efekt, ale je to něco jiného: k id se ukládají potvrzení, takže přejmenování zahodí záznam všem a natrvalo. Měňte since(), ne id. Viz Tour → Co je nového po aktualizaci.

Pořád zaseknutí?

• Znovu si přečtěte dokumentaci konkrétního balíčku pro danou funkci (Forms, Table, Sortable, Core).
• U problémů s runtime/stavem spusťte Integration sadu, zda se chování reprodukuje: vendor/bin/pest --configuration phpunit.xml --testsuite "Integration".
• Zkontrolujte Návod k upgradu, pokud problém začal po aktualizaci.