Laravel Echo Tutorial

Introduction #

Laravel Echo is a JavaScript library that makes it painless to subscribe to channels and listen for events broadcast by your Laravel application. It abstracts the underlying WebSocket implementation (Pusher, Socket.io, Laravel WebSockets, etc.) and provides a clean, expressive API.

Prerequisites #

• Laravel 9+ project
• Composer installed
• Node.js & npm (or Yarn)
• An account on Pusher or the Laravel WebSockets package installed locally

1. Install the required packages #

# Server side (Laravel)
composer require pusher/pusher-php-server
composer require beyondcode/laravel-websockets --dev   # optional, for self‑hosted Pusher replacement

# Client side (JavaScript)
npm install --save laravel-echo pusher-js   # or socket.io-client if you prefer Socket.io

2. Configure broadcasting #

Edit config/broadcasting.php:

'connections' => [
    'pusher' => [
        'driver' => 'pusher',
        'key' => env('PUSHER_APP_KEY'),
        'secret' => env('PUSHER_APP_SECRET'),
        'app_id' => env('PUSHER_APP_ID'),
        'options' => [
            'cluster' => env('PUSHER_APP_CLUSTER'),
            'useTLS' => true,
            // If you are using Laravel WebSockets set host & port:
            // 'host' => '127.0.0.1',
            // 'port' => 6001,
            // 'encrypted' => true,
        ],
    ],
    // other connections …
];

Add the corresponding environment variables in .env:

BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your-app-id
PUSHER_APP_KEY=your-key
PUSHER_APP_SECRET=your-secret
PUSHER_APP_CLUSTER=mt1   # or your cluster

If you use Laravel WebSockets, keep the same keys – the package mimics the Pusher API.

3. Publish and run Laravel WebSockets (optional) #

php artisan vendor:publish --provider="BeyondCode\LaravelWebSockets\WebSocketsServiceProvider" --tag="config"
php artisan websockets:serve

The server will listen on 127.0.0.1:6001 by default.

4. Create a broadcastable event #

php artisan make:event NewMessage

Edit the generated event (app/Events/NewMessage.php):

use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Broadcasting\PrivateChannel;
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;

class NewMessage implements ShouldBroadcast
{
    use InteractsWithSockets;

    public $message;
    public $userId;

    public function __construct($message, $userId)
    {
        $this->message = $message;
        $this->userId = $userId;
    }

    public function broadcastOn()
    {
        return new PrivateChannel('chat.'.$this->userId);
    }
}

Trigger the event somewhere in your app:

event(new NewMessage('Hello world!', auth()->id()));

5. Set up Echo on the front‑end #

Create a JavaScript file, e.g., resources/js/echo.js:

import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window.Pusher = Pusher;

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: process.env.MIX_PUSHER_APP_KEY,
    cluster: process.env.MIX_PUSHER_APP_CLUSTER,
    wsHost: process.env.MIX_ECHO_HOST || window.location.hostname,
    wsPort: 6001,               // use 443 for TLS
    wssPort: 6001,
    forceTLS: false,            // true if using HTTPS & wss
    enabledTransports: ['ws', 'wss'],
});

Add the environment variables to .env (and webpack.mix.js if you use Mix):

MIX_PUSHER_APP_KEY=${PUSHER_APP_KEY}
MIX_PUSHER_APP_CLUSTER=${PUSHER_APP_CLUSTER}
MIX_ECHO_HOST=127.0.0.1   # optional, for self‑hosted websockets

Compile assets:

npm run dev   # or npm run prod

6. Listen for the event in the browser #

window.Echo.private(`chat.${userId}`)
    .listen('NewMessage', (e) => {
        console.log('New message:', e.message);
        // update UI here
    });

Make sure the user is authenticated – Echo automatically sends the Laravel session cookie to authorize private channels.

7. Debugging tips #

• Run php artisan queue:work if your event implements ShouldBroadcastNow? (No, use ShouldBroadcast).
• Check the browser console for any Authentication error – usually caused by missing BroadcastServiceProvider or mismatched CSRF token.
• For self‑hosted WebSockets, open http://localhost:6001 – you should see a dashboard (if the package is installed).
• Use php artisan broadcast:channel to test channel authorization.

Conclusion #

Laravel Echo, paired with Pusher or the open‑source Laravel WebSockets package, brings real‑time capabilities to your Laravel applications with minimal boilerplate. Follow the steps above, and you’ll be able to broadcast events, listen on private channels, and build chat apps, notifications, live dashboards, and more.