discord.js

About

@discordjs/ws is a powerful wrapper around Discord's gateway.

Installation

Node.js 16.9.0 or newer is required.

npm install @discordjs/ws
yarn add @discordjs/ws
pnpm add @discordjs/ws

npm install @discordjs/ws
yarn add @discordjs/ws
pnpm add @discordjs/ws

Optional packages

zlib-sync for WebSocket data compression and inflation (npm install zlib-sync)
bufferutil for a much faster WebSocket connection (npm install bufferutil)
utf-8-validate in combination with bufferutil for much faster WebSocket processing (npm install utf-8-validate)

Example usage

import { WebSocketManager, WebSocketShardEvents } from '@discordjs/ws';
import { REST } from '@discordjs/rest';

const rest = new REST().setToken(process.env.DISCORD_TOKEN);
// This example will spawn Discord's recommended shard count, all under the current process.
const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0, // for no intents
	rest,
});

manager.on(WebSocketShardEvents.Dispatch, (event) => {
	// Process gateway events here.
});

await manager.connect();

import { WebSocketManager, WebSocketShardEvents } from '@discordjs/ws';
import { REST } from '@discordjs/rest';

const rest = new REST().setToken(process.env.DISCORD_TOKEN);
// This example will spawn Discord's recommended shard count, all under the current process.
const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0, // for no intents
	rest,
});

manager.on(WebSocketShardEvents.Dispatch, (event) => {
	// Process gateway events here.
});

await manager.connect();

Specify shards

// Spawn 4 shards
const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0,
	rest,
	shardCount: 4,
});

// The manager also supports being responsible for only a subset of your shards:

// Your bot will run 8 shards overall
// This manager will only take care of 0, 2, 4, and 6
const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0,
	rest,
	shardCount: 8,
	shardIds: [0, 2, 4, 6],
});

// Alternatively, if your shards are consecutive, you can pass in a range
const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0,
	rest,
	shardCount: 8,
	shardIds: {
		start: 0,
		end: 4,
	},
});

// Spawn 4 shards
const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0,
	rest,
	shardCount: 4,
});

// The manager also supports being responsible for only a subset of your shards:

// Your bot will run 8 shards overall
// This manager will only take care of 0, 2, 4, and 6
const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0,
	rest,
	shardCount: 8,
	shardIds: [0, 2, 4, 6],
});

// Alternatively, if your shards are consecutive, you can pass in a range
const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0,
	rest,
	shardCount: 8,
	shardIds: {
		start: 0,
		end: 4,
	},
});

Specify `worker_threads`

You can also have the shards spawn in worker threads:

import { WebSocketManager, WorkerShardingStrategy } from '@discordjs/ws';

const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0,
	rest,
	shardCount: 6,
});

// This will cause 3 workers to spawn, 2 shards per each
manager.setStrategy(new WorkerShardingStrategy(manager, { shardsPerWorker: 2 }));
// Or maybe you want all your shards under a single worker
manager.setStrategy(new WorkerShardingStrategy(manager, { shardsPerWorker: 'all' }));

import { WebSocketManager, WorkerShardingStrategy } from '@discordjs/ws';

const manager = new WebSocketManager({
	token: process.env.DISCORD_TOKEN,
	intents: 0,
	rest,
	shardCount: 6,
});

// This will cause 3 workers to spawn, 2 shards per each
manager.setStrategy(new WorkerShardingStrategy(manager, { shardsPerWorker: 2 }));
// Or maybe you want all your shards under a single worker
manager.setStrategy(new WorkerShardingStrategy(manager, { shardsPerWorker: 'all' }));

Contributing

Before creating an issue, please ensure that it hasn't already been reported/suggested, and double-check the documentation.
See the contribution guide if you'd like to submit a PR.

Help

If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle nudge in the right direction, please don't hesitate to join our official discord.js Server.