Nova Realtime Notification Laravel Package

Getting Started

• Install with composer require yassir3wad/nova-realtime-notification, then publish the package assets/config (php artisan vendor:publish --provider="Yassir3wad\NovaRealtimeNotification\..." — confirm the exact provider/tag in the README, as it may ship a JS asset and a config file).
• Confirm your broadcast stack is working before touching the package: set BROADCAST_CONNECTION (Laravel 11+) or BROADCAST_DRIVER (Laravel 10 and below) to pusher, reverb, or ably, fill the matching credentials in config/broadcasting.php / .env, and verify window.Echo connects from the Nova UI.
• Make sure notifications are actually persisted (Nova's database notification channel) — the package refreshes the notification list, so the list must exist and be queryable through Nova's own endpoint.
• First use case to validate end-to-end: send a single Nova notification to your own user ($user->notify(new SomeNovaNotification(...))), keep the Nova window open, and confirm the bell/list updates without a page reload.
• If nothing happens on that first test, the problem is almost always infrastructure (queue not running, wrong broadcast driver, or channel authorization), not the package.

Implementation Patterns

• Notification-driven flow: continue sending notifications through Laravel's normal Notification classes with toNova()/toDatabase(); the package listens on the broadcast side and refreshes Nova's notification list. You don't change how you author notifications, only how they're delivered (must implement ShouldBroadcast or use a broadcasting channel).
• Event-driven flow: for non-notification UI updates, dispatch a broadcast event on the user's private channel and let the listener refresh. Keep the event payload minimal — the list is re-fetched from Nova's endpoint, so the payload is a trigger, not the data source.
• Queue it: broadcast via queued notifications/events (ShouldBroadcast rather than ShouldBroadcastNow) in production so the HTTP request isn't blocked by the broadcast handshake; run php artisan queue:work alongside your web server.
• Channel naming: keep the per-user private channel (App.Models.User.{id} or the package's configured equivalent) consistent between your broadcast broadcastOn() and routes/channels.php authorization callback. If you use a custom guard or a non-App\Models\User model, update the channel authorization and the package config together.
• Pair with a polling fallback for users behind restrictive networks: realtime is the fast path, but a low-frequency setInterval refresh (or refresh-on-focus) covers dropped websockets.
• Local development loop: php artisan queue:work + npm run dev (or php artisan reverb:start) + browser devtools "WS" tab open. Use BROADCAST_CONNECTION=log temporarily to confirm the event is dispatched before debugging the client.
• Testing: assert the broadcast is dispatched with Event::fake() / Notification::fake() and assertPushed-style assertions; the browser refresh itself is untestable in PHPUnit, so keep the assertion at the dispatch boundary.

Gotchas and Tips

• v1.0.2 changes the client behavior: the notification list now refreshes when the broadcast arrives. If you pinned 1.0.1 and worked around the missing refresh with your own JS listener, polling interval, or Nova.$emit handler, remove it — otherwise you'll double-fetch the notifications endpoint on every broadcast. Bump to ^1.0.2 and delete the workaround in the same PR.
• Refresh ≠ new data delivery: the list re-queries Nova's notification endpoint. If the notification wasn't persisted to the database, or the user lacks authorization for that notification, the list will refresh and show nothing — a confusing "it works but nothing appears" symptom. Check persistence first.
• Version mismatch trap: BROADCAST_DRIVER was renamed to BROADCAST_CONNECTION in Laravel 11. Copying an old .env example will silently leave broadcasting on null and nothing will arrive.
• Echo availability inside Nova: Nova loads its own JS bundle; confirm window.Echo is initialized (via resources/js/bootstrap.js in your app or a Nova asset) and that the package's listener isn't registering before Echo exists. A "listener registered but never fires" bug usually means Echo was undefined at registration time.
• Private channel auth failures show up as 403s on /broadcasting/auth, not as JS errors — check the network tab before assuming the package is broken. Session/CSRF and the Broadcast::channel() callback are the usual culprits.
• Queue + ShouldBroadcastNow in tests: Notification::fake() prevents broadcasting entirely, so a "realtime doesn't work in tests" report is expected behavior, not a regression.
• Multi-tenant / impersonation: if admins impersonate users, the channel authorization must resolve to the impersonated user or the refresh will target the wrong channel and appear to do nothing.
• Extension points: the published config (channel name, event/listener class) and the package's view/JS asset are the intended customization seams — publish rather than editing vendor/. Overriding the JS asset means you own re-applying changes on every composer update, so prefer config where possible.
• Debugging order that saves time: (1) is the event dispatched? (driver log) → (2) does the websocket connection establish? → (3) does /broadcasting/auth return 200? → (4) does the list refresh but stay empty? (persistence/authorization) → (5) does it refresh twice? (leftover workaround).