Notifications Laravel Package

Getting Started

• Install with composer require laravilt/notifications, then look first at the package README.md, config/notifications.php, and the src/ + resources/js/ folders. The config file is the map: it tells you which channels, polling/broadcast behaviour, and UI stack (Vue vs React) the package expects.
• Publish and run what the install docs specify — typically php artisan vendor:publish --tag=laravilt-notifications-config, the asset/stub tags, and php artisan migrate (the package ships its own notifications table migration in addition to Laravel's default). Confirm the table exists before wiring UI.
• Mount the notification bell component in your layout. Since v1.1.0 there are both Vue and React entry points, so pick the one matching your Inertia adapter — mixing them is the single most common first-day mistake.
• First use case: fire one database notification from a domain event and see it land in the bell.

  // app/Notifications/OrderShipped.php extends the package's base Notification (or Laravel's)
  $user->notify(new OrderShipped($order));
  

  Verify the unread badge updates after a page reload before you move on to real-time delivery.

Implementation Patterns

• Stay on Laravel's primitives. Use Notifiable on your User, toDatabase() / toBroadcast() on notification classes, and let the package own the read/unread, listing, and UI endpoints. Wrap package logic rather than reimplementing mark-as-read.
• Shared props for the badge. For Inertia apps, share the unread count and the latest N notifications via HandleInertiaRequests so the bell renders server-side on first paint; let the package's client component take over for live updates. This avoids the flash of an empty bell.
• Two delivery modes, pick deliberately. Polling is the zero-infrastructure default; broadcasting (Reverb/Pusher + php artisan queue:work) gives instant updates. Broadcasting requires a queue worker and correct channels.php auth for the private user channel — test with queue:work running, not sync.
• Notifications as UI state, not just rows. Model the payload (title, body, icon, url, actions) so the same record renders in the dropdown, a full notifications page, and any future email digest. Keep the payload serialisable and free of Eloquent models.
• React support (new in 1.1.0). If you're on React, import the React component entry point rather than the Vue one and check the package's JS build/stub tags include React stubs. Expect to re-run your asset build after upgrading.
• Grouping and actions. For high-volume domains (comments, mentions, order events), group by subject key and store a subject reference so users see "3 new replies" instead of three rows. Add explicit action endpoints rather than links that mutate state on GET.

Gotchas and Tips

• Re-publish assets after upgrading. v1.1.0 changes the JS layer (React entry points, hardened Vue state updates). Stale published Vue components are the likely cause if the bell stops reacting after composer update.
• Vue state hardening is a behaviour change, not just a refactor. If you previously mutated the notification array/props directly from your own code, switch to the package's exposed methods (mark read, refresh, dismiss). Symptom of getting this wrong: badge and list drift out of sync until a hard reload.
• Laravel 13 compatibility is a floor bump, not a free upgrade. Check composer.json constraints across your whole app before pulling 1.1.0 in; a package supporting 13 may still run on 12, but transitive Laravilt packages must agree.
• Most of the changelog is CI noise. The Dependabot entries (checkout, setup-node, gh-release, fetch-metadata) don't affect your runtime — don't chase them when debugging.
• Debugging checklist for "no notifications appear": is the row in the DB (rules out the notification class), is the notifiable morph correct, is the component actually mounted, is the polling interval/broadcast connection configured, and are there queued jobs stuck (php artisan queue:failed).
• Migration collisions. If you already have Laravel's default notifications table, don't let the package migration recreate it — check the published migration and guard with Schema::hasTable.
• Extension points: publish the config to override polling interval, channel list, and pagination; publish the views/components to restyle; subclass the package notification to add your own toDatabase() payload shape. Prefer config/views over editing vendor/ so upgrades stay clean.