Nova Websockets Laravel Package

Getting Started

Treat this package as a thin Nova integration for beyondcode/laravel-websockets, not as a websocket server or a full monitoring product. The first question is whether your Nova/Laravel version is compatible: the package was last released in 2019 and is most likely suited to Nova 2.x-era applications. Check composer.json constraints before adopting it in a modern Nova 4/5 app.

Minimal adoption path:

1. Make sure beyondcode/laravel-websockets is already installed, configured, and working outside Nova. Confirm the dashboard route (usually /laravel-websockets) and broadcasting config are correct.
2. Install the package:

   composer require vemcogroup/nova-websockets
   

3. Read the package README first, then inspect src/ for the service provider and Nova tool class. Look specifically for:
   • publishes() / config tags,
   • the Nova tool class,
   • whether it embeds an iframe, redirects, or implements its own dashboard,
   • any hardcoded /laravel-websockets path.
4. Register the tool in app/Providers/NovaServiceProvider.php:

   use Vemcogroup\NovaWebsockets\NovaWebsockets;
   
   public function tools()
   {
       return [
           new NovaWebsockets(),
       ];
   }
   

   Confirm the exact class name in the package source if your installed tag differs.
5. Run any publish command documented by the package, then clear caches:

   php artisan config:clear
   php artisan route:clear
   php artisan nova:publish
   

6. Start the websocket server and queue worker in the environment you are testing:

   php artisan websockets:serve
   php artisan queue:work
   

7. Open Nova, find the WebSockets tool/menu item, and verify it shows the laravel-websockets dashboard. First real use case: give admins/ops a single-pane link to active websocket connections and metrics without remembering a separate /laravel-websockets URL.

If the package only adds an iframe or link around the existing laravel-websockets dashboard, your day-to-day value is mostly convenience and access control, not new websocket functionality.

Implementation Patterns

Use the package as a Nova-facing entry point while keeping websocket configuration in config/websockets.php and broadcasting in config/broadcasting.php. Avoid duplicating app key, port, or TLS settings inside Nova code.

Common patterns:

• Admin monitoring shortcut: Put the tool behind Nova’s normal authentication and expose it only to trusted operators. This is useful in staging or internal admin panels where checking active connections and test broadcasts is part of support.
• Environment-specific dashboard URL: If the package supports configuration, point it at the correct dashboard path per environment. If it hardcodes /laravel-websockets, either standardize that route everywhere or fork/override the tool component.
• Authorization in two places: Restrict the Nova tool and also restrict the laravel-websockets dashboard route middleware. A Nova-only gate is not enough if /laravel-websockets remains publicly reachable.
• Debug workflow: Open the Nova tool, trigger a broadcast from php artisan tinker or a test event, then watch connections and events in the dashboard. Keep browser DevTools open to inspect the WebSocket handshake and wss:// connection.
• Proxy/TLS integration: In production, terminate TLS at your proxy and forward both the websocket upgrade path and the dashboard path. Ensure Nova and the websocket dashboard are served from compatible origins to avoid mixed-content or iframe blocking.
• Extension point: If the packaged tool is too limited, publish its views/assets if possible, override the Vue tool component, or replace the tool with a small custom Nova tool that embeds or links to the laravel-websockets dashboard with your own health checks and authorization.
• Operational separation: Use this package for human inspection only. Use Supervisor/systemd for websockets:serve, a queue worker for broadcasts, and external monitoring for uptime/alerting.

A practical support workflow is: support engineer opens Nova → WebSockets → checks whether clients are connected → triggers a test broadcast → confirms whether the issue is server, auth, or client subscription. That is the main day-to-day leverage.

Gotchas and Tips

• Legacy risk is the biggest gotcha. Last release was 2019, with only 14 stars. Expect Composer conflicts with modern Nova, Laravel, PHP, and laravel-websockets versions. Validate on a branch before committing.
• The package does not run the websocket server. If the dashboard is empty, first check that php artisan websockets:serve is running and that clients are actually connecting.
• Dashboard exposure is dangerous. The laravel-websockets dashboard can reveal app keys, connection stats, and test-event controls. Restrict it with middleware/Gates and do not leave it public in production.
• Iframe/CSP issues are common. If the Nova tool embeds the dashboard, browser console errors about X-Frame-Options, frame-ancestors, or mixed content mean you need same-origin hosting, proxy changes, or a non-iframe link.
• Config cache hides changes. After editing dashboard paths, broadcasting settings, or package config, run php artisan config:clear and restart workers/servers as needed.
• Key/port mismatches cause silent failures. Verify PUSHER_APP_KEY, host, port, TLS, and the client’s Echo configuration. A dashboard showing “connected” does not guarantee private-channel auth is working.
• Stats are ephemeral. laravel-websockets dashboard metrics are in-memory and reset on restart. Do not use them for auditing or long-term capacity planning.
• Route collisions and trailing slashes. Check php artisan route:list | grep -i websocket if the Nova tool 404s. Subdirectory deployments and missing trailing slashes can break hardcoded dashboard URLs.
• Debug from both sides. Use browser DevTools for the WebSocket handshake, storage/logs/laravel.log for server/auth errors, and php artisan websockets:serve -vvv where supported. Confirm the queue worker is consuming broadcast jobs.
• Prefer direct access or a custom tool on modern stacks. If the package is incompatible, a simple Nova link/tool to the existing laravel-websockets dashboard is usually safer than maintaining an abandoned 2019 wrapper.