0
# Pusher Channels JavaScript
1

2
Pusher Channels JavaScript library enables real-time bidirectional communication between clients and servers through WebSocket connections with automatic fallback to HTTP polling. It provides pub/sub messaging, presence channels, user authentication, and client-side event triggering across web browsers, React Native, Node.js, and web workers.
3

4
## Package Information
5

6
- **Package Name**: pusher-js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install pusher-js`
10

11
## Core Imports
12

13
```typescript
14
import Pusher from "pusher-js";
15
import { Channel, PresenceChannel, Members } from "pusher-js";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const Pusher = require("pusher-js");
22
```
23

24
For Node.js specifically:
25

26
```javascript
27
const Pusher = require("pusher-js/dist/node/pusher");
28
```
29

30
## Basic Usage
31

32
```typescript
33
import Pusher from "pusher-js";
34

35
// Initialize Pusher client
36
const pusher = new Pusher("your-app-key", {
37
  cluster: "us2",
38
  forceTLS: true
39
});
40

41
// Subscribe to a channel
42
const channel = pusher.subscribe("my-channel");
43

44
// Bind to events
45
channel.bind("my-event", (data) => {
46
  console.log("Received data:", data);
47
});
48

49
// Global event binding
50
pusher.bind("connection_established", () => {
51
  console.log("Connected to Pusher");
52
});
53

54
// Connect and disconnect
55
pusher.connect();
56
// pusher.disconnect();
57
```
58

59
## Architecture
60

61
Pusher-js is built around several key components:
62

63
- **Pusher Client**: Main client class managing connections and global events
64
- **Channel System**: Public, private, and presence channels for different messaging patterns
65
- **Connection Manager**: WebSocket management with automatic reconnection and transport fallback
66
- **Authentication System**: Channel authorization and user authentication for private/presence channels
67
- **Runtime Abstraction**: Platform-specific implementations for web, Node.js, React Native, and web workers
68
- **Event System**: Comprehensive event binding and dispatching throughout the library
69

70
## Capabilities
71

72
### Client Management
73

74
Core Pusher client functionality for establishing connections, managing global events, and controlling the overall WebSocket connection lifecycle.
75

76
```typescript { .api }
77
class Pusher {
78
  constructor(app_key: string, options: Options);
79
  connect(): void;
80
  disconnect(): void;
81
  bind(event_name: string, callback: Function, context?: any): Pusher;
82
  unbind(event_name?: string, callback?: Function, context?: any): Pusher;
83
  bind_global(callback: Function): Pusher;
84
  unbind_global(callback?: Function): Pusher;
85
  unbind_all(callback?: Function): Pusher;
86
  send_event(event_name: string, data: any, channel?: string): boolean;
87
  signin(): void;
88
  shouldUseTLS(): boolean;
89
}
90

91
interface Options {
92
  cluster: string;
93
  authEndpoint?: string;
94
  authTransport?: AuthTransport;
95
  channelAuthorization?: ChannelAuthorizationOptions;
96
  userAuthentication?: UserAuthenticationOptions;
97
  forceTLS?: boolean;
98
  enableStats?: boolean;
99
  disabledTransports?: Transport[];
100
  enabledTransports?: Transport[];
101
  activityTimeout?: number;
102
  pongTimeout?: number;
103
  unavailableTimeout?: number;
104
  wsHost?: string;
105
  wsPort?: number;
106
  wssPort?: number;
107
  httpHost?: string;
108
  httpPort?: number;
109
  httpsPort?: number;
110
  nacl?: any;
111
}
112
```
113

114
[Client Management](./client-management.md)
115

116
### Channel Communication
117

118
Channel-based pub/sub messaging system supporting public channels, private authenticated channels, and presence channels with member tracking.
119

120
```typescript { .api }
121
subscribe(channel_name: string): Channel;
122
unsubscribe(channel_name: string): void;
123
channel(name: string): Channel;
124
allChannels(): Channel[];
125

126
class Channel {
127
  constructor(name: string, pusher: Pusher);
128
  bind(event: string, callback: Function, context?: any): Channel;
129
  unbind(event?: string, callback?: Function, context?: any): Channel;
130
  trigger(event: string, data: any): boolean;
131
  subscribe(): void;
132
  unsubscribe(): void;
133
}
134

135
class PresenceChannel extends Channel {
136
  members: Members;
137
}
138

139
class Members {
140
  count: number;
141
  myID: any;
142
  me: any;
143
  get(id: string): any;
144
  each(callback: Function): void;
145
}
146
```
147

148
[Channel Communication](./channel-communication.md)
149

150
### Authentication
151

152
Authentication and authorization system for private channels, presence channels, and user authentication with customizable auth handlers.
153

154
```typescript { .api }
155
interface ChannelAuthorizationOptions {
156
  transport: 'ajax' | 'jsonp';
157
  endpoint: string;
158
  params?: any;
159
  headers?: any;
160
  paramsProvider?: () => any;
161
  headersProvider?: () => any;
162
  customHandler?: ChannelAuthorizationHandler;
163
}
164

165
interface UserAuthenticationOptions {
166
  transport: 'ajax' | 'jsonp';
167
  endpoint: string;
168
  params?: any;
169
  headers?: any;
170
  paramsProvider?: () => any;
171
  headersProvider?: () => any;
172
  customHandler?: UserAuthenticationHandler;
173
}
174

175
type ChannelAuthorizationHandler = (
176
  params: ChannelAuthorizationRequestParams,
177
  callback: ChannelAuthorizationCallback
178
) => void;
179

180
type UserAuthenticationHandler = (
181
  params: UserAuthenticationRequestParams,
182
  callback: UserAuthenticationCallback
183
) => void;
184
```
185

186
[Authentication](./authentication.md)
187

188
### Connection Management
189

190
Low-level connection management with WebSocket handling, automatic reconnection, transport fallback, and connection state monitoring.
191

192
```typescript { .api }
193
class ConnectionManager {
194
  state: string;
195
  connection: Connection;
196
  socket_id: string;
197
  connect(): void;
198
  disconnect(): void;
199
  send(data: any): boolean;
200
  send_event(name: string, data: any, channel?: string): boolean;
201
  isUsingTLS(): boolean;
202
}
203

204
interface ConnectionCallbacks {
205
  message?: (event: any) => void;
206
  ping?: () => void;
207
  pong?: () => void;
208
  error?: (error: any) => void;
209
  closed?: () => void;
210
}
211
```
212

213
[Connection Management](./connection-management.md)
214

215
## Error Types
216

217
```typescript { .api }
218
class BadEventName extends Error {
219
  constructor(msg?: string);
220
}
221

222
class BadChannelName extends Error {
223
  constructor(msg?: string);
224
}
225

226
class HTTPAuthError extends Error {
227
  status: number;
228
  constructor(status: number, msg?: string);
229
}
230

231
class RequestTimedOut extends Error {
232
  constructor(msg?: string);
233
}
234

235
class TransportClosed extends Error {
236
  constructor(msg?: string);
237
}
238

239
class UnsupportedFeature extends Error {
240
  constructor(msg?: string);
241
}
242
```
243

244
## Platform Support
245

246
Pusher-js supports multiple JavaScript environments:
247

248
- **Web Browsers**: Full WebSocket and HTTP polling support with JSONP fallback
249
- **Node.js**: Server-side WebSocket client for backend applications  
250
- **React Native**: Mobile-optimized implementation with network state detection
251
- **Web Workers**: Background thread support for web applications
252

253
Each platform has optimized transport layers and runtime-specific features while maintaining the same core API.