Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pusher
✓ import Pusher from 'pusher-js';
✗ const Pusher = require('pusher-js');
Standard ES Module import for client-side usage. For CommonJS, use `require`.
Pusher (with encryption)
✓ import Pusher from 'pusher-js/with-encryption';
✗ import Pusher from 'pusher-js';
Use this specific path for encrypted channel support to include necessary encryption primitives.
Pusher (CommonJS)
✓ const Pusher = require('pusher-js');
✗ import Pusher from 'pusher-js';
CommonJS `require` syntax for Node.js environments or older bundlers. For encrypted channels, use `require('pusher-js/with-encryption')`.
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);
Debug
Known issues
gotchaFor 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.fixChange 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). affects: >=7.0.0
breakingThe `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`.fixReview 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.
affects: >=8.5.0
gotchaVersions 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.fixUpgrade to `pusher-js` version 8.5.0 or later to ensure all previous options, including custom handlers, are properly retained when `switchCluster` is invoked.
affects: 8.4.0-rc1 - 8.4.3
breakingMultiple 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.fixIt 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.
affects: <8.4.1, <8.4.3
Errors
Common errors & fixes
Module not found: Can't resolve 'pusher-js/with-encryption'
Attempting to use encrypted channels without the correct import path.
fixEnsure 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
Attempting to subscribe to a `private-` or `presence-` channel without providing a `userAuthentication` or `channelAuthorization` callback in the Pusher client options.
fixConfigure 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
Incorrect cluster name provided during Pusher client initialization, leading to an inability to resolve the WebSocket endpoint.
fixDouble-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', ... }
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.
fixVerify 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.
Audit
Dependencies
No dependency data recorded yet.