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.