Repository navigation
Home
Welcome to the official documentation for @m3rcena/bridge β the unified, cross-platform state synchronization and communication protocol designed to connect Discord bots, web dashboards, REST APIs, and WebSockets.
@m3rcena/bridge solves the fundamental challenge of building modern Discord bots: cross-platform synchronization. Traditionally, Discord bots live in isolation; building a web dashboard meant hacking together custom webhooks, polling databases, or creating brittle custom WebSocket implementations.
@m3rcena/bridge decouples business logic from presentation:
- Headless Engines: Run games, economy actions, or moderation headlessly without requiring Discord interaction objects.
- Bi-directional Synchronization: Changes made in Discord reflect on the dashboard in real-time, and actions dispatched from the dashboard execute instantaneously inside Discord.
-
Universal Package Routers: Any package (
@m3rcena/weky,@m3rcena/eco, or your own custom bot systems) mounts directly into the Bridge viaBridgePackageRouter. - Targeted Audio & Haptics: Stream real-time sound cues and toast notifications to specific web dashboard users or global sessions.
-
Universal Client SDK: Plug-and-play browser client (
@m3rcena/bridge/client) with native React hooks (useBridgeSession), automatic reconnection, and state synchronization. -
Native SQLite & Prisma Handlers: Built-in zero-config local SQLite (
node:sqlite) and auto-migrating Prisma ORM storage.
Explore the comprehensive guides below:
| Guide | Description |
|---|---|
| ποΈ Architecture & Design | Core controller, session lifecycle, presence tracking, and storage adapters. |
| π Connecting Packages | How to connect @m3rcena/weky, @m3rcena/eco, or custom packages to the bridge. |
| π‘ REST & WebSocket Protocol | Full HTTP endpoint specifications and real-time WebSocket protocol frames. |
| π» Client SDK & React Hooks | Integrating dashboards with React, Vue, Next.js, and vanilla JavaScript. |
Install @m3rcena/bridge alongside your Discord bot or web backend:
# npm
npm install @m3rcena/bridge
# pnpm
pnpm add @m3rcena/bridge
# yarn
yarn add @m3rcena/bridge-
Node.js:
>= 22.0.0(Nativefetch,crypto, and ES Modules) -
TypeScript:
>= 5.0(Full type safety) -
ws:
^8.18.0(Included)
import { M3rcenaBridge, BridgeServer } from "@m3rcena/bridge";
import { WekyManager } from "@m3rcena/weky";
import { EcoManager } from "@m3rcena/eco";
// 1. Create Bridge Controller
export const bridge = new M3rcenaBridge({
database: "sqlite", // Zero configuration! Auto-creates ./bridge.sqlite with sessions & kv tables
autoCleanEndedSessions: false,
sessionTimeoutMs: 30 * 60 * 1000,
});
// 2. Connect packages seamlessly β either via constructor or fluent bridge.use()!
// Pattern A: Constructor injection (both accept { bridge } directly)
export const weky = new WekyManager(client, { bridge });
export const eco = new EcoManager({ bridge });
// Pattern B: Fluent chaining on the bridge
// bridge.use(weky).use(eco);
// 3. Launch Standalone Gateway Server (or attach to Express)
export const bridgeServer = new BridgeServer(bridge, {
port: 4000,
path: "/bridge",
});
await bridgeServer.start();
console.log("π Bridge Gateway running at http://localhost:4000/bridge");import React from "react";
import { BridgeClient, useBridgeSession } from "@m3rcena/bridge/client";
const client = new BridgeClient({
url: "ws://localhost:4000/bridge",
userId: "102794864",
autoConnect: true,
});
export function GameDashboard({ sessionId }: { sessionId: string }) {
const { session, isConnected, dispatchAction } = useBridgeSession(client, sessionId);
if (!isConnected) return <div>Connecting to Bridge Gateway...</div>;
if (!session) return <div>Waiting for active session...</div>;
return (
<div className="game-card">
<h2>Session: {session.type} ({session.id})</h2>
<p>Current Turn: {session.currentTurnId}</p>
<button onClick={() => dispatchAction("make_move", { index: 4 })}>
Play Move (Center)
</button>
</div>
);
}Need help? Check out our Connecting Packages Guide or open an issue on GitHub.
GitHub: M3rcena/m3rcena-bridge β’ NPM: @m3rcena/bridge
- Connecting @m3rcena/weky
- Connecting @m3rcena/eco
- Mounting Custom Routers
- Universal Mounting Standard
- Standalone HTTP & WebSocket Server
- Attaching to Express / Fastify / Next.js
- Complete REST API Route Reference
- Real-Time WebSocket Frame Specification
- Browser & Node Client
- React Hooks & useBridgeSession
- Handling Audio Cues & Haptics
- Sending Inbound Moves