Pusher Channels Javascript Client

!test badge

This Pusher Channels client library supports web browsers, web workers and Node.js

If you're looking for the Pusher Channels server library for Node.js, use pusher-http-node instead.

For tutorials and more in-depth information about Pusher Channels, visit our official docs.

For reporting issues, bugs, and feature requests, please feel free to open a pull request or open an issue. If you do not receive a timely response, feel free to check our support portal.

Usage Overview

The following topics are covered:

• Installation

• Initialization
• Configuration
• Global Configuration
• Connection

• Subscribing to Channels (Public and Private)
• Accessing Channels
• Binding to Events
• Default events
• Developing

Supported platforms

• Web

* Angular (See Angular tutorial) * React (See React tutorial) * Vue.js (see Vue.js tutorial)

• React Native
• Node.js

Installation

Web

If you're using Pusher Channels on a web page, you can install the library via:

Encrypted Channel Support

The encryption primitives required to power encrypted channels increase the bundle size quite significantly. In order to keep bundle sizes down, the default web and worker builds of pusher-js no longer support encrypted channels.

If you'd like to make use of encrypted-channels, you need to import the with-encryption builds as described below.

Yarn (or NPM)

You can use any NPM-compatible package manager, including NPM itself and Yarn.

yarn add pusher-js

Then:

import Pusher from 'pusher-js';

If you'd like to use encrypted channels:

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

Or, if you're not using ES6 modules:

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

If you'd like to use encrypted channels:

const Pusher = require('pusher-js/with-encryption');

CDN

<script src="https://js.pusher.com/7.0/pusher.min.js"></script>

If you'd like to use encrypted channels:

<script src="https://js.pusher.com/7.0/pusher-with-encryption.min.js"></script>

You can also use cdnjs.com if you prefer or as a fallback.

Bower (discouraged)

Or via Bower:

bower install pusher

and then:

<script src="bower_components/pusher/dist/web/pusher.min.js"></script>

Typescript

We've provided typescript declarations since v5.1.0. Most things should work out of the box but if you need access to specific types you can import them like so:

import Pusher from 'pusher-js';
import * as PusherTypes from 'pusher-js';
var presenceChannel: PusherTypes.PresenceChannel;
...

React Native

⚠️ Important notice

> React Native support has been deprecated and soon will be removed from this repository.

> Please, use our official React Native SDK instead.

Web Workers

importScripts('https://js.pusher.com/7.0/pusher.worker.min.js');

If you'd like to use encrypted channels:

importScripts('https://js.pusher.com/7.0/pusher-with-encryption.worker.min.js');

If you're building your worker with a bundler, you can import the worker entrypoint

import Pusher from 'pusher-js/worker'

If you'd like to use encrypted channels:

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

Node.js

Having installed pusher-js via an NPM-compatible package manager, run:

import Pusher from 'pusher-js';

Notes:

• For standard WebWorkers, this build will use HTTP as a fallback.
• For ServiceWorkers, as the XMLHttpRequest API is unavailable, there is currently no support for HTTP fallbacks. However, we are open to requests for fallbacks using fetch if there is demand.

Initialization

const pusher = new Pusher(APP_KEY, {
  cluster: APP_CLUSTER,
});

You can get your APP_KEY and APP_CLUSTER from the Pusher Channels dashboard.

Configuration

There are a number of configuration parameters which can be set for the client, which can be passed as an object to the Pusher constructor, i.e.:

const pusher = new Pusher(APP_KEY, {
  cluster: APP_CLUSTER,
  channelAuthorization: {
    endpoint: 'http://example.com/pusher/auth'
  },
});

For most users, there is little need to change these. See client API guide for more details.

forceTLS (Boolean)

Forces the connection to use TLS. When set to false the library will attempt non-TLS connections first. Defaults to true.

userAuthentication (Object)

Object containing the configuration for user authentication. Valid keys are:

• endpoint (String) - Endpoint on your server that will return the authentication signature needed for signing the user in. Defaults to /pusher/user-auth.

• transport (String) - Defines how the authentication endpoint will be called. There are two options available: