{"id":13426,"library":"laravel-echo-server","title":"Laravel Echo Server","description":"Laravel Echo Server is a Node.js-based server that acts as a backend for Laravel Echo, facilitating real-time event broadcasting using Socket.io. It bridges Laravel's server-side events with client-side JavaScript applications, allowing for seamless real-time features like notifications and chat. The current stable version is 1.6.3, last updated in April 2021. While not actively undergoing rapid feature development, it remains a stable and maintained solution for self-hosted real-time functionality. Key differentiators include its tight integration with the Laravel broadcasting system, providing an authentication mechanism against the Laravel application, and offering a convenient Command Line Interface (CLI) for setup and management. It supports both Redis and SQLite for persisting presence channel members and offers flexible configuration options for hosting and security (e.g., SSL, CORS).","status":"maintenance","version":"1.6.3","language":"javascript","source_language":"en","source_url":"https://github.com/tlaverdure/Laravel-Echo-Server","tags":["javascript","laravel","socket.io"],"install":[{"cmd":"npm install laravel-echo-server","lang":"bash","label":"npm"},{"cmd":"yarn add laravel-echo-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add laravel-echo-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is the client-side JavaScript library that communicates with laravel-echo-server. While not a direct npm dependency of the server, it's a critical part of the ecosystem for client-side functionality.","package":"laravel-echo","optional":false},{"reason":"The core real-time communication library used by laravel-echo-server for WebSocket connections.","package":"socket.io","optional":false},{"reason":"Required for Redis database backend to store presence channel members and for broadcasting events from Laravel to the Echo server.","package":"redis","optional":true},{"reason":"The Laravel PHP framework is required (version 5.3+ generally, 6.5.2+ for certain features like Redis prefixing) to provide the authentication endpoint and event broadcasting system that laravel-echo-server interacts with.","package":"laravel/framework","optional":false},{"reason":"Laravel Echo Server is a Node.js application and requires Node.js runtime (6.0+) to function.","package":"node","optional":false}],"imports":[{"note":"For programmatic usage (e.g., embedding the server within another Node.js application), the `Server` class is the primary export. While CommonJS `require` works, ESM `import` is preferred in modern Node.js applications.","wrong":"const Server = require('laravel-echo-server');","symbol":"Server","correct":"import { Server } from 'laravel-echo-server';"},{"note":"The package is primarily used via its globally installed CLI tool. Direct programmatic imports for the CLI functions are less common than simply running the commands.","wrong":"node_modules/.bin/laravel-echo-server init","symbol":"CLI Commands","correct":"laravel-echo-server init"},{"note":"While not a code import, the `laravel-echo-server.json` file is the central way to configure the server, including `authHost`, `port`, `databaseConfig`, and `sslCertPath`. Environment variables can override some options.","symbol":"Configuration options","correct":"// Refer to laravel-echo-server.json"}],"quickstart":{"code":"npm install -g laravel-echo-server\n\n# Navigate to your Laravel project root\ncd my-laravel-app\n\n# Initialize the configuration file. Follow prompts.\n# This creates laravel-echo-server.json\nlaravel-echo-server init\n\n# Add an API client for HTTP broadcasting (optional but recommended)\n# Replace APP_ID with your desired application ID\nlaravel-echo-server client:add APP_ID\n\n# Start the server\nlaravel-echo-server start\n\n// Example client-side setup with laravel-echo (in resources/js/bootstrap.js or similar)\nimport Echo from 'laravel-echo';\nimport { io } from 'socket.io-client';\n\nwindow.io = io;\n\nwindow.Echo = new Echo({\n    broadcaster: 'socket.io',\n    host: window.location.hostname + ':6001' // Or your server's host/port\n});\n\n// Listen for a public channel event\nwindow.Echo.channel('my-public-channel')\n    .listen('MyEvent', (e) => {\n        console.log('Received event:', e);\n    });","lang":"javascript","description":"Demonstrates global installation, initialization, API client setup, starting the server, and basic client-side listening using Laravel Echo."},"warnings":[{"fix":"Ensure your Laravel application is running version 6.5.2+ if you intend to use Redis prefixing. Update your `composer.json` and run `composer update`.","message":"Redis prefixing functionality (added in v1.6.0) requires Laravel Framework version 6.5.2 or higher to operate correctly.","severity":"breaking","affected_versions":">=1.6.0"},{"fix":"Set `devMode: false` in your `laravel-echo-server.json` file for production deployments. You can also control this via `LARAVEL_ECHO_SERVER_DEBUG` environment variable.","message":"Using `devMode: true` in production environments can lead to excessive logging, potentially exposing sensitive information or impacting performance. It's intended for debugging only.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Properly configure the `apiOriginAllow` option in `laravel-echo-server.json` to include the origins of your client-side applications. Example: `\"apiOriginAllow\": {\"allowCors\": true, \"allowOrigin\": \"*\", \"allowMethods\": [\"GET\", \"POST\"], \"allowHeaders\": [\"Origin\", \"Content-Type\", \"X-Auth-Token\", \"X-Requested-With\", \"Accept\", \"Authorization\", \"X-CSRF-TOKEN\", \"X-Socket-ID\"]}`","message":"CORS configuration for the HTTP API (`apiOriginAllow`) is crucial for client-side applications to communicate with the server if they are hosted on different domains/ports. Misconfiguration can lead to blocked requests.","severity":"gotcha","affected_versions":">=1.3.2"},{"fix":"Provide the full path to your SSL certificate chain file in the `sslCertChainPath` option within `laravel-echo-server.json`.","message":"When using SSL (HTTPS/WSS), ensure `sslCertChainPath` is configured if your SSL certificate includes a chain. Forgetting this can lead to `ERR_CERT_AUTHORITY_INVALID` errors in clients.","severity":"gotcha","affected_versions":">=1.3.1"},{"fix":"Verify `authHost` in `laravel-echo-server.json` matches your Laravel application's URL. Ensure Laravel's `.env` file has `APP_KEY` set and `BROADCAST_DRIVER=redis` (or another appropriate driver) if using Redis for broadcasting.","message":"The `authHost` setting must correctly point to your Laravel application's host for private and presence channel authentication. Incorrect values or missing `APP_KEY` in Laravel's `.env` can prevent authentication.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the package globally using `npm install -g laravel-echo-server` or `yarn global add laravel-echo-server`.","cause":"The `laravel-echo-server` package was not installed globally or is not in your system's PATH.","error":"laravel-echo-server: command not found"},{"fix":"Ensure your Redis server is running and accessible from the machine hosting `laravel-echo-server`. Verify the `host`, `port`, and `password` settings in your `laravel-echo-server.json`.","cause":"The Redis server is not running or the `databaseConfig.redis` settings in `laravel-echo-server.json` are incorrect.","error":"Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED"},{"fix":"Check your `laravel-echo-server.json` for correct `authHost` and `apiOriginAllow` settings. Ensure you have an API client generated with `laravel-echo-server client:add APP_ID` and that `APP_ID` and `auth_key` are correctly passed in your client-side Echo configuration if using API authentication.","cause":"Client-side authentication or API access issues. This could be due to incorrect `authHost`, missing API client ID/key, or CORS policy blocking the connection.","error":"WebSocket connection to 'ws://localhost:6001/socket.io/?EIO=3&transport=websocket' failed: Error during WebSocket handshake: Unexpected response code: 403"},{"fix":"Verify that your Laravel application is running, the `authEndpoint` (default `/broadcasting/auth`) is correct, and your Laravel broadcasting routes are properly configured and accessible to the Echo server. Check Laravel logs for authentication errors.","cause":"The Laravel authentication endpoint (`authEndpoint`) is unreachable, misconfigured, or not returning a successful authentication response for private/presence channels.","error":"Error: Request to authentication endpoint returned error."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"laravel-echo-server","cli_version":null}