Pusher Channels JavaScript Client

Common errors

• Module not found: Can't resolve 'pusher-js/with-encryption'

  cause Attempting to use encrypted channels without the correct import path.
  fix Ensure you are importing from `pusher-js/with-encryption` for encrypted channel support, instead of the default `pusher-js` path.

• Pusher: Auth handler not provided for private/presence channel

  cause Attempting to subscribe to a `private-` or `presence-` channel without providing a `userAuthentication` or `channelAuthorization` callback in the Pusher client options.
  fix Configure an authentication endpoint or a custom `userAuthentication` / `channelAuthorization` function in your Pusher client initialization options to authorize access to private/presence channels.

• Pusher: Unknown host: ws-mt1.pusher.com

  cause Incorrect cluster name provided during Pusher client initialization, leading to an inability to resolve the WebSocket endpoint.
  fix Double-check the `cluster` option when initializing Pusher (e.g., `'eu'`, `'us2'`, `'ap2'`) against your Pusher dashboard settings. Ensure it's a valid Pusher cluster.

• Pusher: WebSocket connection failed: Event { isTrusted: true, type: 'error', ... }

  cause The WebSocket connection could not be established, often due to network issues, incorrect app key, invalid TLS settings (e.g., `forceTLS: false` with HTTPS origin), or firewall restrictions.
  fix Verify your `appKey` and `cluster` are correct. Ensure `forceTLS: true` is set if your application is served over HTTPS. Check browser console for more specific WebSocket errors and network connectivity.

Warnings

• gotcha For encrypted channels, you must explicitly import from `pusher-js/with-encryption`. The default `pusher-js` import does not include the necessary encryption primitives to keep bundle sizes down.
  Fix: Change your import statement from `import Pusher from 'pusher-js';` to `import Pusher from 'pusher-js/with-encryption';` (for ES Modules) or `const Pusher = require('pusher-js/with-encryption');` (for CommonJS).
• breaking The `AuthOptionsT` type was refactored to a discriminated union (`InternalAuthOptions | CustomAuthOptions`) in v8.5.0 for improved type safety. This might cause TypeScript compilation errors if you have custom authentication handlers or intricate type definitions related to `AuthOptionsT`.
  Fix: Review and update your TypeScript definitions for custom authentication handlers to conform to the new discriminated union type. Refer to the official `pusher-js` documentation or source for the updated `AuthOptionsT` structure.
• gotcha Versions prior to 8.5.0 might not correctly persist custom options (like authentication handlers) when using the `switchCluster` method, which was introduced in 8.4.0-rc1. This could lead to unexpected behavior or disconnections upon cluster switching.
  Fix: Upgrade to `pusher-js` version 8.5.0 or later to ensure all previous options, including custom handlers, are properly retained when `switchCluster` is invoked.
• breaking Multiple security vulnerabilities in transitive dependencies (e.g., `express`, `qs`, `lodash`, `node-forge`) were patched in versions 8.4.1 and 8.4.3. Older versions are susceptible to these known CVEs.
  Fix: It is highly recommended to upgrade to the latest stable version of `pusher-js` (8.5.0 or newer) to benefit from critical security patches and ensure your application is protected against known vulnerabilities.

Install

• npm install pusher-js npm
• yarn add pusher-js yarn
• pnpm add pusher-js pnpm

Imports

• Pusher
  wrong:

  const Pusher = require('pusher-js');

  correct:

  import Pusher from 'pusher-js';

  Standard ES Module import for client-side usage. For CommonJS, use `require`.
• Pusher (with encryption)
  wrong:

  import Pusher from 'pusher-js';

  correct:

  import Pusher from 'pusher-js/with-encryption';

  Use this specific path for encrypted channel support to include necessary encryption primitives.
• Pusher (CommonJS)
  wrong:

  import Pusher from 'pusher-js';

  correct:

  const Pusher = require('pusher-js');

  CommonJS `require` syntax for Node.js environments or older bundlers. For encrypted channels, use `require('pusher-js/with-encryption')`.

Quickstart

Demonstrates initializing a Pusher client, connecting, subscribing to a public channel, and binding to a custom event. Includes handling connection status.

import Pusher from 'pusher-js';

// Replace with your actual Pusher app key and cluster
const PUSHER_APP_KEY = process.env.PUSHER_APP_KEY ?? 'YOUR_APP_KEY';
const PUSHER_APP_CLUSTER = process.env.PUSHER_APP_CLUSTER ?? 'eu'; // e.g., 'eu', 'us2'

if (PUSHER_APP_KEY === 'YOUR_APP_KEY') {
  console.warn('Pusher app key not set. Using a placeholder. Replace YOUR_APP_KEY and PUSHER_APP_CLUSTER with your actual credentials.');
}

const pusher = new Pusher(PUSHER_APP_KEY, {
  cluster: PUSHER_APP_CLUSTER,
  forceTLS: true // Always use TLS for production
});

pusher.connection.bind('connected', () => {
  console.log('Pusher client connected!');
});

pusher.connection.bind('disconnected', () => {
  console.log('Pusher client disconnected!');
});

const channel = pusher.subscribe('my-channel');

channel.bind('my-event', function(data: any) {
  console.log('Received event on my-channel:', data);
});

// To simulate receiving an event (typically sent from a server):
// setTimeout(() => {
//   console.log('Simulating event trigger...');
//   // This part would typically be handled by your server sending an event
//   // For client-side simulation, you might use a debug API or similar.
// }, 5000);

console.log('Pusher client initialized and attempting to connect...');

// You can switch cluster dynamically (since v8.5.0)
// setTimeout(() => {
//   console.log('Switching cluster to us2...');
//   pusher.switchCluster('us2');
// }, 10000);