Connect your Discord Bot Ecosystem to Web Dashboards, REST APIs, and WebSockets.
The shared, production-grade bridge standard for all @m3rcena packages.
๐ Complete Documentation Wiki: For detailed architecture guides, package router specs, and client SDK walkthroughs, visit the @m3rcena/bridge Official Wiki:
Instead of implementing custom, duplicate bridge code inside each separate Discord bot package (@m3rcena/weky, @m3rcena/eco, etc.), @m3rcena/bridge provides a single, high-performance universal synchronization standard:
- ๐ Multi-Module Registry: Mount multiple bot disciplines (
games,economy,moderation,custom) on a single unified bridge gateway. - ๐ Real-Time State Synchronization: Live WebSocket push updates whenever sessions, matches, or inventories change.
- ๐ฎ Cross-Platform Action Dispatching: Seamlessly trigger game moves, economy transactions, or admin actions from Web Dashboards, REST APIs, or Discord bots with correlated response handling.
- ๐ Targeted Scoped Audio & Notifications: Broadcast audio cues (MP3 sounds) and notifications strictly to the active player's browser session with presence filtering (
requireOnlinePresenceForAudio). - ๐ฅ User Presence Tracking: Detect when dashboard users connect or disconnect with instant online/offline state.
- ๐พ Native SQLite & Enterprise Prisma Handlers: Built-in zero-dependency local SQLite (
node:sqliteWAL mode) and auto-migrating Prisma ORM storage adapters. - ๐ฆ Rust-Style Submodule Resolver: Install and host via Git submodules locally with zero npm dependencies or transparently fall back to npm.
- ๐ป Universal Client SDK: Ready-to-use client SDK exported directly via
@m3rcena/bridge/clientfor Next.js, React, Vue, Electron, or Node.js. - ๐ค Discord.js v14.28.1 Ready: Fully compatible with the latest Discord.js updates and
clientReadylifecycle.
npm install @m3rcena/bridge
# or
pnpm add @m3rcena/bridge
# or
yarn add @m3rcena/bridgeYou can vendor and host @m3rcena/bridge locally via Git submodules without needing to publish or pull from npm:
git submodule add https://github.com/M3rcena/m3rcena-bridge.git submodules/m3rcena-bridgeAdd auto-registration at the top of your app entrypoint:
import "@m3rcena/bridge/register";Or run standalone hosting:
npx tsx @m3rcena/bridge/host --port 4000@m3rcena/bridge provides flexible, production-grade persistence adapters:
import {
M3rcenaBridge,
SqliteBridgeStorage,
PrismaBridgeStorage,
JsonFileStorageAdapter,
MemoryStorageAdapter,
} from "@m3rcena/bridge";
// 1. Zero-dependency Local SQLite (node:sqlite with WAL Mode)
const sqliteStorage = new SqliteBridgeStorage({ path: "./data/bridge.sqlite" });
// 2. Or Enterprise Prisma ORM Storage
// const prismaStorage = new PrismaBridgeStorage(prismaClient);
// 3. Or Lightweight JSON File Storage
// const jsonStorage = new JsonFileStorageAdapter("./data/bridge.json");
// Pass storage directly to Bridge controller
export const bridge = new M3rcenaBridge({
storage: sqliteStorage,
requireOnlinePresenceForAudio: true,
});import { M3rcenaBridge, BridgeServer, SqliteBridgeStorage } from "@m3rcena/bridge";
import { WekyManager } from "@m3rcena/weky";
import { EcoManager } from "@m3rcena/eco";
// 1. Create Bridge Controller with SQLite WAL Persistence
export const bridge = new M3rcenaBridge({
storage: new SqliteBridgeStorage({ path: "./data/bridge.sqlite" }),
requireOnlinePresenceForAudio: true,
});
// 2. Connect packages seamlessly (Both constructor and fluent styles supported!)
// Style A: Pass bridge into managers
const weky = new WekyManager(client, { bridge });
const eco = new EcoManager({ bridge });
// Style B: Or chain on the bridge directly
// bridge.use(weky).use(eco);
// 3. Start the Real-Time WebSocket Server Gateway
const server = new BridgeServer(bridge, {
port: 4000,
path: "/bridge",
secretToken: "your_secure_bridge_secret",
});
await server.start();
console.log("๐ Bridge WebSocket Gateway running at ws://localhost:4000/bridge");Import the lightweight client SDK directly:
import { createBridgeClient } from "@m3rcena/bridge/client";
// 1. Connect to the Bridge (pass secretToken via query param or client config)
const client = createBridgeClient({
url: "ws://localhost:4000/bridge?token=your_secure_bridge_secret",
token: "your_secure_bridge_secret",
userId: "1447491639550410796", // Authenticated Discord user ID
username: "M3rcena",
platform: "dashboard",
});
await client.connect();
// 2. Subscribe to live match or session state
const unsubscribe = client.subscribeSession("sess_fight_123", (newState) => {
console.log("Live State Update:", newState);
// Update your React / Vue state
});
// 3. Dispatch moves/actions directly from your dashboard UI
const result = await client.dispatchAction("games", "sess_fight_123", "hit");
console.log("Action Result:", result);
// 4. Listen for targeted sound cues
client.onAudioCue(({ soundKey, soundUrl }) => {
new Audio(soundUrl).play();
});
// 5. Listen for real-time notifications
client.onNotification(({ title, message, type }) => {
showToast(`${title}: ${message}`);
});Get a real-time overview of all connected users, active games, and system stats for your dashboard home screen:
const overview = await bridge.getDashboardOverview();
console.log(overview);
/*
{
activeModules: ["games", "economy"],
onlineUsersCount: 14,
onlineUsers: [{ userId: "123", username: "Alpha", platform: "dashboard" }],
activeSessionsCount: 3,
activeSessions: [...],
uptime: 3600000,
stats: { totalActionsDispatched: 85, totalSessionsCreated: 12 }
}
*/Distributed under the Apache-2.0 License. See LICENSE for details.
Engineered with โค๏ธ by M3rcena