shardwire

Typed bridge between a Discord.js bot process and separate app code over WebSocket.

npm · Documentation · Reference

npm install shardwire

The Problem

Keeping every feature inside the same process as the Discord gateway works until it does not: deploys get riskier, resource contention shows up, and you may not want dashboards or automation sharing the exact same runtime as session management.

Shardwire is the small middle layer: expose a bridge from the bot package, connect from another Node process (or a bundler target) with shardwire/client, and move product logic behind the same contracts you would use in a normal internal API—except the transport is WebSocket-oriented for low-latency Discord-shaped traffic.

See It Work

Minimal shape (see docs for complete options and error handling):

// Bot process (Node): create bridge alongside your Client
import { createBotBridge } from 'shardwire';

const bridge = createBotBridge({
	// discord.js client, listen options, secret, ...
});
await bridge.ready();

// App process: connect as a client
import { connectBotBridge } from 'shardwire/client';

const session = connectBotBridge({
	url: process.env.SHARDWIRE_URL!,
	secret: process.env.SHARDWIRE_SECRET!,
});

Install

At runtime, traffic follows your Discord.js configuration (Discord gateway/REST) and any bridge WebSocket server you start. Put the bridge secret and bot credentials in your environment; the library does not add its own outbound analytics. Remove the dependency with npm uninstall shardwire in the consuming project.

npm install shardwire

Requires Node.js 22+.

| Import | Use when | | ------------------ | ------------------------------------------------------------- | | shardwire | Bot-side bridge creation, types shared with the app | | shardwire/client | App-side connector (Node or bundlers that resolve the export) |

Build artifacts live under dist/ on npm; TypeScript types ship with the package.

Getting Started

1. Read How it works.
2. Follow Getting started or the tutorial.
3. Use npm create shardwire@latest if you prefer a ready-made layout.

How It Works

shardwire pairs a bot-hosted bridge with a client that speaks the same protocol. Authentication is based on a shared secret (optionally scoped); mismatches fail closed—treat URL and secret as one unit when debugging.

Migration-friendly modes

• createBotBridge({ mode: 'split' }) — default two-process architecture.
• createBotBridge({ mode: 'hybrid', exposeClient: true }) — split mode plus optional bot.client() access to the underlying discord.js client.
• createBotBridge({ mode: 'single-process' }) — no WebSocket transport; use bot.app() to run app handlers in-process.

For unsupported Discord surface, enable raw passthrough (raw.enabled) and call app.raw(...) / app.actions.runRaw(...) with a strict allowlist.

• Connection errors (ECONNREFUSED, TLS mismatches): verify listen URL vs client URL, reachable host/port, then secret alignment.
• API surface: reference index and troubleshooting.
• Package changelog: shardwire changelog.

FAQ

Is discord.js required? This package lists discord.js as a dependency and targets that ecosystem; use the docs for supported versions.

Can I use this without React? Yes. React lives in @shardwire/react, not here.

Contributing

Issues and PRs: github.com/unloopedmido/shardwire (monorepo). Run package verification from packages/shardwire with npm run verify.

License

MIT — see LICENSE in this package.