Wirelist Laravel Package

Getting Started

• composer require edulazaro/wirelist, then publish whatever the README instructs — typically a config tag and a views tag (php artisan vendor:publish --tag=wirelist-config, --tag=wirelist-views). Confirm the exact tag names from the README; the package's published docs are thin and the release note for 1.1.0 is an empty compare link, so treat the README and the published config file as the authoritative API surface.
• Confirm you have Livewire installed and that your layout renders @livewireStyles / @livewireScripts. Wirelist is Livewire-driven for search, sort, and pagination, so nothing works without the Livewire runtime. Note the description also mentions Alpine — the layout/grid toggles are likely client-side, so make sure Alpine is booting in the same layout.
• Read these three things in this order, in about 30 minutes: the README, config/wirelist.php after publishing (default page size, column definitions, view paths, layout mode), and the component class itself. The config file is the fastest way to learn what is configurable versus what requires a subclass.
• First use case: drop the list onto an existing admin or dashboard screen to render a paginated, sortable, searchable Eloquent listing, and pick a layout — divided rows, separate cards, or a grid — via the config or a component prop. Something along the lines of:

<livewire:wire-list :query="$users" />

• Do this on a non-critical screen with real data shape first. The fastest way to learn the package is to see how it handles your actual column types (dates, relations, booleans, statuses) before committing a layout.

Implementation Patterns

• Prefer a query builder over a collection. Pass an Eloquent builder so search, sort, and pagination remain database-side. Passing a hydrated collection defeats the package's main value and pushes the whole table into the Livewire payload.
• Columns: config for toggles, subclass for logic. Use the published config for simple visibility and ordering. As soon as a column needs a computed value, a formatted date, a relation, or a badge, subclass the list component and override its column definition method. Keeping formatting logic in a subclass rather than Blade keeps it testable.
• Layout as a per-screen decision. Rows suit dense tabular data; cards suit records with a thumbnail and a few key fields; grid suits media or product catalogues. Decide per screen rather than globally — the layout is a presentation choice, not an app-wide setting.
• Row rendering via published views. The customization hook is the Blade view. Publish it, copy it into resources/views/vendor/... or your own namespace, and point the component at your copy. This is where you put per-row actions, status pills, and links.
• Actions belong behind policies. Built-in edit/delete handlers and any custom row actions should call $this->authorize(...) or Gate::allows(...). The package renders a list; it does not know your authorization model. Centralize this in a base subclass so every list in the app inherits the check.
• Search and filter through the URL. Bind filter inputs with wire:model (or wire:model.live on Livewire 3) so the list re-queries on update, and let the component's query-string support make filtered views bookmarkable. This is the single biggest day-to-day ergonomic win: shareable filtered list URLs.
• Wrap it once. Put the package behind your own Blade partial or a thin base component (App\Livewire\BaseList). Every screen then uses your wrapper, and swapping or forking the package later is a one-file change rather than a grep across the codebase.
• Compose rather than extend for toolbars. For "New record", export buttons, or bulk actions, put your own toolbar above the list component in the parent Blade view instead of reaching into the package's render method. Less coupling, easier to test.
• Test with Livewire's test helpers. Livewire::test(YourList::class)->set('search', 'foo')->assertSee(...) covers search, sort, and pagination behaviour cheaply. Do this once per list component — it protects you against upstream behaviour changes on upgrade.
• Refresh after mutations. After a create/update/delete elsewhere on the page, dispatch the appropriate Livewire event or use $refresh so the list re-queries. wire:poll works for near-real-time lists but watch the query load on busy screens.

Gotchas and Tips

• Livewire 2 vs 3 is the first thing to verify. Check the package's composer.json constraint for livewire/livewire before you write anything. If you are on Livewire 3 and the package targets 2 (or vice versa), stop — this is a hard incompatibility, not a workaround.
• Re-publishing views overwrites your customizations. On every package upgrade, diff the published views against the package's originals rather than blindly republishing. Keep your customized copies under your own view namespace so a vendor:publish --force cannot silently destroy them.
• N+1 is the default failure mode. Columns that touch relations will lazy-load per row. Eager-load everything the columns reference on the builder you pass in, and verify with DB::listen or Laravel Debugbar on a realistic dataset. This is the bug most likely to reach production.
• Search performance degrades quietly. Free-text search across columns usually means LIKE '%term%', which cannot use an index. Fine at a few thousand rows; painful at a hundred thousand. Know your table size before shipping and consider a full-text index or a scope that limits searchable columns.
• Sort keys need a whitelist. User-controlled sort columns are a classic SQL injection surface if the component interpolates them. Verify how the package handles the sort parameter, and restrict sortable columns in your config or subclass regardless.
• Authorization is not automatic. The package does not enforce your policies. Every action — built-in edit/delete included — needs a gate check. Test it by hitting an action as an unauthorized user.
• Alpine/Livewire state can desync. If a layout or grid/card toggle is Alpine-side, a Livewire re-render (pagination, search) can reset it. If the toggle matters to users, persist it in the component's public properties rather than in Alpine's x-data.
• No build step is a feature and a trap. Tailwind classes baked into the package's views may be purged by your own Tailwind config. If cards or grids render unstyled, safelist the package's classes or ship a small CSS file alongside your published views.
• Config caching. Run php artisan config:cache after changing config/wirelist.php in production; use config:clear locally when a config change appears to have no effect.
• Debugging recipe. Use Livewire's browser devtools to inspect the component payload, DB::listen to count queries per interaction, and assertSee/assertSet in a Livewire test to pin behaviour. If the component renders but does not react, it is almost always missing Livewire scripts in the layout or an outdated published view.
• Upgrade discipline matters more here than usual. Version 1.1.0 shipped with no changelog — only a compare link. Read the 1.0.1...1.1.0 diff before upgrading, pin the exact version during evaluation, and configure Renovate/Dependabot to require manual approval for this package specifically. Auto-merge is not appropriate for a single-maintainer UI package with no release notes.
• Keep the exit door open. The package is presentational, which is good news — your wrapper component and a per-list Livewire test suite are the entire removal cost. Document in the component's docblock how to replace it, because that knowledge is what gets lost six months in.