Pusher Batch Auth Plugin

0.0.2 verified Sat Apr 25 auth: no javascript

A plugin for the Pusher JavaScript library (v4.1.x) that batches multiple private and presence channel authentication requests into a single HTTP call. Version 0.0.2 is the latest stable release, with low release cadence. It reduces network overhead when subscribing to many channels simultaneously by aggregating auth requests into one POST. Key differentiator: enables batch authentication endpoint (not available in Pusher's default authorizer). Requires Pusher JS 4.1+ and a server endpoint that handles batched requests.

Common errors

error Uncaught TypeError: pusher.subscribe is not a function ↓

cause Pusher library not loaded before the plugin or incorrect initialization.

fix

Ensure pusher-js is loaded and initialized (e.g., import Pusher from 'pusher-js') before using the plugin.

error PusherBatchAuthorizer is not defined ↓

cause Plugin script not loaded or incorrect import path.

fix

If using script tags, include pusher-auth.js after pusher.min.js. If using npm, ensure the package is installed and imported correctly.

error Server returned invalid auth response ↓

cause The batched auth endpoint returned an unexpected JSON format.

fix

Ensure the server returns a JSON object with channel names as keys, each containing status and data fields as documented.

Warnings

breaking Version 0.0.2 is only compatible with Pusher 4.1.x and above. Using older Pusher versions will cause issues. ↓

fix Use version 2.0.0 of this plugin for Pusher 4.0 and older, or upgrade Pusher to >=4.1.0.

gotcha The server endpoint must handle batched requests. If it expects single channel auth, batch subscriptions will fail. ↓

fix Implement a batched auth endpoint that accepts multiple channel_name[] parameters and returns a JSON object per channel.

gotcha authDelay defaults to 0; if subscriptions are triggered in separate ticks, multiple requests may still occur. Increase delay to batch across ticks. ↓

fix Set authDelay to a value like 200ms to accumulate subscriptions from different ticks into a single request.

deprecated Package is on npm as 'helpscout-pusher-js-auth' but the plugin's original repository is 'pusher-js-auth'. The npm package may be a fork. ↓

fix Consider using the original 'pusher-js-auth' package from npm for better community support.

Install

npm install helpscout-pusher-js-auth

yarn add helpscout-pusher-js-auth

pnpm add helpscout-pusher-js-auth

Imports

PusherBatchAuthorizer
wrong
```
const PusherBatchAuthorizer = require('pusher-js-auth');
```
correct
```
import PusherBatchAuthorizer from 'pusher-js-auth';
```
ESM default import; CJS require also works but is not recommended for bundlers. The global variable is 'PusherBatchAuthorizer' when using script tags.

PusherBatchAuthorizer

wrong

import { PusherBatchAuthorizer } from 'pusher-js-auth';

correct

const PusherBatchAuthorizer = require('pusher-js-auth');

CJS require; named import is incorrect because the package exports a single default.

PusherBatchAuthorizer
wrong
```
<script src="node_modules/pusher-js-auth/dist/pusher-auth.js"></script>
```
correct
```
<script src="lib/pusher-auth.js"></script>
```
Script tag usage: the plugin exposes 'PusherBatchAuthorizer' globally. Node_modules path is fragile; use the provided lib file after building.

Quickstart

Initializes Pusher with batch authorizer, subscribes to multiple channels to demonstrate single auth request.

import Pusher from 'pusher-js';
import PusherBatchAuthorizer from 'pusher-js-auth';

const pusher = new Pusher('YOUR_APP_KEY', {
  cluster: 'us2',
  authorizer: PusherBatchAuthorizer,
  authDelay: 200,
  authEndpoint: 'https://example.com/pusher/auth',
});

const channel1 = pusher.subscribe('private-channel-1');
const channel2 = pusher.subscribe('presence-channel-2');

channel1.bind('pusher:subscription_succeeded', () => {
  console.log('Subscribed to channel1');
});
channel2.bind('pusher:subscription_succeeded', () => {
  console.log('Subscribed to channel2');
});

// The plugin will batch both auth requests into a single HTTP call.