ShardManager

ShardManager from @lunibee/sharding manages multiple Gateway connections (shards) for bots serving more than 2,500 guilds. It supports automatic shard count discovery, per-shard info, and horizontal reconnect logic.

Import

TypeScript

import { ShardManager } from "@lunibee/sharding";
// or via the main package:
import { ShardManager } from "lunibee";

JavaScript

import { ShardManager } from "@lunibee/sharding";
// or via the main package:
import { ShardManager } from "lunibee";

Constructor

TypeScript

new ShardManager(options: ShardManagerOptions)

JavaScript

new ShardManager(options )

Option	Type	Description
token	string	Discord bot token.
intents	GatewayIntentResolvable	Gateway intents for all shards.
shardCount	number | "auto"	Number of shards. "auto" fetches Discord’s recommendation.
presence	GatewayPresence	Initial presence for all shards.
autoScale	boolean	Automatically rescale shards over time.

Properties

Property	Type	Description
shards	Map<number, Gateway>	Map of shard ID to Gateway instance.

Methods

connect()

Starts all shards. Uses shardCount: "auto" to query Discord for the recommended count.

TypeScript

await manager.connect();

JavaScript

await manager.connect();

destroy()

Closes all shard connections and clears the shard map.

TypeScript

manager.destroy();

JavaScript

manager.destroy();

fetchRecommendedShardCount()

Fetches the recommended shard count from Discord’s /gateway/bot endpoint.

TypeScript

const count = await manager.fetchRecommendedShardCount();
console.log(`Recommended shards: ${count}`);

JavaScript

const count = await manager.fetchRecommendedShardCount();
console.log(`Recommended shards: ${count}`);

getShardIdForGuild(guildId)

Calculates which shard handles a given guild ID using Discord’s formula:

shardId = (guildId >> 22) % totalShards

TypeScript

const shardId = manager.getShardIdForGuild("123456789012345678");
console.log(`Guild is on shard ${shardId}`);

JavaScript

const shardId = manager.getShardIdForGuild("123456789012345678");
console.log(`Guild is on shard ${shardId}`);

broadcast(payload)

Sends a raw Gateway payload to all shards.

info()

Returns an array of ShardInfo objects:

TypeScript

const info = manager.info();
for (const shard of info) {
  console.log(`Shard ${shard.id}: ${shard.state} — ping ${shard.ping}ms`);
}

JavaScript

const info = manager.info();
for (const shard of info) {
  console.log(`Shard ${shard.id}: ${shard.state} — ping ${shard.ping}ms`);
}

ShardInfo shape:

TypeScript

interface ShardInfo {
  id: number;
  state: GatewayState;
  ping: number;
  guilds: number; // only available if guild count tracking is enabled
}

JavaScript

  id;
  state: GatewayState;
  ping;
  guilds; // only available if guild count tracking is enabled
}

Example

TypeScript

import { ShardManager, IntentBits } from "lunibee";

const manager = new ShardManager({
  token: process.env.DISCORD_TOKEN!,
  intents: [IntentBits.guilds, IntentBits.guildMessages],
  shardCount: "auto",
});

await manager.connect();
console.log(`Running ${manager.shards.size} shards.`);

// Graceful shutdown
process.on("SIGINT", () => {
  manager.destroy();
  process.exit(0);
});

JavaScript

import { ShardManager, IntentBits } from "lunibee";

const manager = new ShardManager({
  token: process.env.DISCORD_TOKEN,
  intents: [IntentBits.guilds, IntentBits.guildMessages],
  shardCount: "auto",
});

await manager.connect();
console.log(`Running ${manager.shards.size} shards.`);

// Graceful shutdown
process.on("SIGINT", () => {
  manager.destroy();
  process.exit(0);
});

[!NOTE] Sharding is only required for bots in 2,500+ guilds. For smaller bots, use Client directly.

ClusterManager

For very large bots (100k+ guilds), use ClusterManager from @lunibee/sharding to distribute shards across multiple processes:

TypeScript

import { ClusterManager } from "@lunibee/sharding";

const cluster = new ClusterManager({
  token: process.env.DISCORD_TOKEN!,
  script: "./dist/bot.js",  // worker script path
  shardCount: "auto",
  clusterCount: 4,          // number of CPU worker processes
});

await cluster.connect();

JavaScript

import { ClusterManager } from "@lunibee/sharding";

const cluster = new ClusterManager({
  token: process.env.DISCORD_TOKEN,
  script: "./dist/bot.js",  // worker script path
  shardCount: "auto",
  clusterCount ,          // number of CPU worker processes
});

await cluster.connect();