{"id":16664,"library":"pusher-js-auth","title":"Pusher-js Batch Authentication Plugin","description":"Pusher-js-auth is a client-side plugin designed to enhance the official `pusher-js` library by batching multiple private and presence channel authentication requests into a single HTTP call. This significantly improves performance and reduces network overhead when an application subscribes to numerous channels concurrently. The current stable version is 4.0.1, which is compatible exclusively with `pusher-js` versions 7.x and later. Older `pusher-js` versions (6.x and below) require the 3.x release of this plugin. While the project's release cadence is tied to major `pusher-js` updates, it provides a consistent solution for optimizing authentication workflows. Key differentiators include its seamless integration via the `authorizer` option in the `Pusher` client, and configurable `authDelay` for managing request timing. It requires a custom server-side authentication endpoint capable of processing batched channel names and returning a consolidated JSON response, which Pusher's server libraries can facilitate.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"git://github.com/dirkbonhomme/pusher-js-auth","tags":["javascript","pusher","client","auth","typescript"],"install":[{"cmd":"npm install pusher-js-auth","lang":"bash","label":"npm"},{"cmd":"yarn add pusher-js-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add pusher-js-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency; this plugin extends pusher-js functionality.","package":"pusher-js","optional":false}],"imports":[{"note":"The `PusherBatchAuthorizer` function is provided as a named export for ES Module environments. It is also available as a global variable (PusherBatchAuthorizer) when loaded via a script tag in browsers.","wrong":"import PusherBatchAuthorizer from 'pusher-js-auth';","symbol":"PusherBatchAuthorizer","correct":"import { PusherBatchAuthorizer } from 'pusher-js-auth';"},{"note":"In CommonJS environments, `PusherBatchAuthorizer` is accessed via named property destructuring from the module export.","wrong":"const PusherBatchAuthorizer = require('pusher-js-auth');","symbol":"PusherBatchAuthorizer","correct":"const { PusherBatchAuthorizer } = require('pusher-js-auth');"}],"quickstart":{"code":"import Pusher from 'pusher-js'; // Assuming 'pusher-js' is installed\nimport { PusherBatchAuthorizer } from 'pusher-js-auth';\n\n// Your Pusher app key (replace with environment variable in production)\nconst PUSHER_APP_KEY = process.env.PUSHER_APP_KEY ?? 'YOUR_APP_KEY';\n// Your Pusher cluster (e.g., 'us2', 'eu')\nconst PUSHER_APP_CLUSTER = process.env.PUSHER_APP_CLUSTER ?? 'YOUR_CLUSTER';\n// The endpoint on your server that handles batch authentication\nconst AUTH_ENDPOINT = process.env.PUSHER_AUTH_ENDPOINT ?? '/pusher/batch-auth';\n\n// Initialize Pusher client with the batch authorizer\nconst pusher = new Pusher(PUSHER_APP_KEY, {\n    cluster: PUSHER_APP_CLUSTER,\n    authorizer: PusherBatchAuthorizer,\n    authDelay: 200, // Optional: delay in milliseconds before executing auth request\n    authEndpoint: AUTH_ENDPOINT // Ensure this points to your server-side batch auth handler\n});\n\n// Subscribe to multiple private and presence channels\n// The PusherBatchAuthorizer will automatically batch authentication requests for these\n// into a single HTTP call to the authEndpoint.\nconst privateChannel1 = pusher.subscribe('private-chat-1');\nconst privateChannel2 = pusher.subscribe('private-messages-user-abc');\nconst presenceChannel = pusher.subscribe('presence-online-users');\n\n// Example of binding to an event on a channel\nprivateChannel1.bind('client-message', (data: any) => {\n    console.log('Received message on private-chat-1:', data);\n});\n\npresenceChannel.bind('pusher:member_added', (member: any) => {\n    console.log(`Member added to presence-online-users: ${member.id}`);\n});\n\nconsole.log('Pusher client initialized and channels subscribed. Authentication requests will be batched.');\n","lang":"typescript","description":"This quickstart demonstrates how to initialize the Pusher client with the `PusherBatchAuthorizer` and subscribe to multiple channels, showcasing how the plugin automatically batches authentication requests."},"warnings":[{"fix":"If using `pusher-js` v6 or older, downgrade this plugin to `pusher-js-auth` v3.x (`npm install pusher-js-auth@3`). For `pusher-js` v7+, ensure `pusher-js-auth` v4+ is used.","message":"Pusher-js-auth v4.x is explicitly incompatible with `pusher-js` versions 6.0 and older. Using this version of the plugin with an older `pusher-js` client will lead to authentication failures.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Implement or update your auth endpoint to parse `channel_name[0]`, `channel_name[1]`, etc., from incoming POST data. The endpoint must return a JSON object where keys are channel names and values are their respective authentication data or error statuses (e.g., `{'private-a': { 'auth': '...' }, 'private-c': { 'status': 403 }}`).","message":"Your server-side authentication endpoint must be designed to handle batched authentication requests. It expects an array of `channel_name` parameters and should return a batched JSON response.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consider experimenting with `authDelay` if you observe unexpected authentication timing or wish to further optimize batching for extremely rapid channel subscriptions. For subscriptions within the same event loop, a value of 0 is typically sufficient.","message":"The `authDelay` option (defaulting to 0 milliseconds) allows fine-tuning when authentication requests are sent. While it can be as low as 0, the very first authentication request is always internally postponed until the connection to Pusher is successfully established, regardless of this setting.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify your server-side authentication endpoint's logic. Ensure it correctly parses the batched channel names from the request and returns a JSON object with valid authentication data or appropriate error statuses for each requested channel, following the `pusher-js-auth` expected output format.","cause":"The server-side authentication endpoint did not provide a valid batched response for one or more channels, or explicitly rejected authentication for a specific channel (e.g., with a 403 HTTP status).","error":"Pusher: Auth channel failed for private-channel (403)"},{"fix":"Ensure `pusher-js-auth` is correctly installed (`npm install pusher-js-auth`) and imported (`import { PusherBatchAuthorizer } from 'pusher-js-auth';` or `const { PusherBatchAuthorizer } = require('pusher-js-auth');`). Additionally, confirm that your `pusher-js` version is 7 or higher if you are using `pusher-js-auth` v4+.","cause":"The `PusherBatchAuthorizer` symbol was not correctly imported or loaded before being passed to the `Pusher` client constructor, or it's being used with an incompatible `pusher-js` version.","error":"TypeError: PusherBatchAuthorizer is not a constructor"}],"ecosystem":"npm"}