Wiretoast Laravel Package

Product Decisions This Supports

• Build vs. buy for UI feedback. Toasts are undifferentiated plumbing, not a differentiator. This package is one composer require, one <x-wiretoast /> tag in the layout, and one $this->notify() line per action — versus a sprint of custom Blade partials, JS listeners, and z-index debugging. The buy side wins decisively; the only question worth debating is which library.
• Closing the "feedback debt" backlog. Replace the ad-hoc mix of session()->flash() banners, bespoke alert partials, and silent mutations with one consistent pattern. This is a roadmap item that historically gets deferred because it's unglamorous — it ships in an afternoon now.
• Deferring design decisions without blocking engineering. 11 bundled themes + 7 positions + CSS-variable custom themes means design can pick or brand a look after the feature lands, in app.css, not in a PR against business logic. It also decouples us from Tailwind/Bootstrap, so the choice survives a future restyle.
• Semantic urgency as a product policy. The 5 types plus timeout: 0 for errors establishes a rule we can write down: success ephemeral, failures persistent until read. That's a UX standard, not a technical one — the PM owns it.
• Scoping which surfaces need feedback first. Highest-value targets are action confirmations after mutations, form validation errors, and destructive-action results. Group mode handles bulk imports where one-toast-per-row would otherwise bury the viewport.
• Risk-capping through abstraction. Because the API is identical across PHP, Alpine, and vanilla JS, we route every call through a two-line internal wrapper. That single decision converts "adopt a 2-star package" into "adopt any toast library, with a one-file swap if needed."

When to Consider This Package

Consider it when:

• The stack is Laravel 11+/PHP 8.2+, ideally with Livewire 3 or Alpine already in the front end.
• We need standard feedback patterns and want them standardized cheaply — the value is in the convention, not the library.
• We want zero JS dependencies and no CSS framework coupling, and asset loading can go through Vite (the recommended path, and the one Laravel 11+ makes default).
• We're willing to own the abstraction layer. If the package is used directly at forty call sites, we've bought a liability, not a tool.

Look elsewhere when:

• We need interactive notifications. No action buttons, no "Undo," no rich content in the README. If the roadmap includes undoable or actionable toasts, this doesn't cover it.
• Accessibility is a compliance gate. The README makes no ARIA, focus-management, or screen-reader announcements. In a regulated or publicly-procured product that's a blocking unknown — verify before committing, or choose a library with documented a11y guarantees.
• Support and longevity are procurement requirements. Two stars, zero dependents, a single maintainer, and a 1.0.x line released within months. There is no SLA and no community to lean on.
• The stack isn't Laravel. The Blade component and $this->notify() helper are the substance; the "framework-agnostic" framing is generous.
• We need server-pushed notifications from queued or long-running jobs. Toast delivery is client-side; queue workers can't reach a browser. That becomes a polling concern we build ourselves.

The honest risk statement: this is a young, low-adoption package. The mitigation is structural, not wishful — MIT license means we can fork and vendor it permanently if the maintainer disappears. That is an acceptable, quantified risk only behind our own wrapper.

How to Pitch It (Stakeholders)

To executives: We can close a persistent "product feels unpolished after actions" complaint in roughly one engineering day, using a free MIT-licensed library with no license cost, no vendor contract, and no added runtime dependencies. It's a small, reversible bet — and because the code is MIT and we'll consume it through a thin internal wrapper, a bad outcome costs us an afternoon to undo, not a migration.

To engineering: One composer require, one Blade tag in the layout, assets through the existing Vite bundle (no second HTTP request, no separate cache-busting setup). No Tailwind, no Bootstrap, no JS dependency tree. Testable by asserting the dispatched event rather than the DOM. The one trap is loading assets twice — once via Vite and once via :assets="true" — which silently double-fires every toast; we'll pick the Vite path and document it.

To design: 11 production-quality themes plus full CSS-variable control, automatic and opt-in dark mode, and theming by attribute on any ancestor — so brand styling lives in our stylesheet and can ship independently of the notification logic.

The ask: approval to adopt behind an internal wrapper, with a written convention (errors persist, successes auto-dismiss, all calls go through window.toast/our base-component helper). If we skip the wrapper, we shouldn't adopt at all.