Repository navigation
Installation and Setup
This page covers installation requirements, standard package managers (npm/pnpm/yarn/bun), local Git submodule installation, the Rust-style Submodule Resolver, and standalone local hosting for @m3rcena/bridge.
-
Node.js:
>= 22.0.0(LTS 22, 24, 26). -
Dependencies: Zero external dependencies for core Bridge;
wsfor real-time WebSocket server.
If you prefer standard package management via npm registry:
# npm
npm install @m3rcena/bridge ws
# pnpm
pnpm add @m3rcena/bridge ws
# yarn
yarn add @m3rcena/bridge ws
# bun
bun add @m3rcena/bridge wsIf you prefer vendoring and hosting @m3rcena/bridge locally via Git submodules rather than installing from the npm registry, @m3rcena/bridge features a Rust/Cargo-inspired Submodule Resolver.
git submodule add https://github.com/M3rcena/m3rcena-bridge.git submodules/m3rcena-bridge
git submodule update --init --recursiveAdd this single line at the top of your entrypoint:
import "@m3rcena/bridge/register";Or pass it as a flag when executing Node / TSX:
# TSX
tsx -r @m3rcena/bridge/register src/index.ts
# Node.js
node --import @m3rcena/bridge/register dist/index.js-
Local-First Discovery: Automatically scans
./submodules/m3rcena-bridge,./vendor/m3rcena-bridge,./packages/m3rcena-bridge,./libs/m3rcena-bridge. -
Transparent Interception: Patches module resolution so
import { M3rcenaBridge } from '@m3rcena/bridge'redirects seamlessly to your local submodule without changing your code. -
NPM Fallback: If the local submodule is absent, it falls back to standard
node_modules/@m3rcena/bridge. -
Source vs Build: In TypeScript environments (
tsx,ts-node), it automatically loads TypeScript sources directly.
For instant IDE autocompletion directly from the local submodule sources:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"paths": {
"@m3rcena/bridge": [
"./submodules/m3rcena-bridge/src",
"./submodules/m3rcena-bridge/dist/index.mjs",
"./submodules/m3rcena-bridge"
],
"@m3rcena/bridge/client": [
"./submodules/m3rcena-bridge/src/client",
"./submodules/m3rcena-bridge/dist/client.mjs"
]
}
}
}π‘ Tip: You can generate the exact paths object dynamically in Node:
import { generateTsConfigPaths } from "@m3rcena/bridge/resolver"; console.log(generateTsConfigPaths());
{
"submodulesDir": "./submodules",
"preferSource": true,
"packages": {
"@m3rcena/bridge": "./submodules/m3rcena-bridge"
}
}Or via environment variable:
export M3RCENA_BRIDGE_PATH="./submodules/m3rcena-bridge"@m3rcena/bridge can be hosted as an independent real-time WebSocket and HTTP gateway server!
Inside the submodule directory:
cd submodules/m3rcena-bridge
npm install
npm run hostThis starts the Bridge Gateway Server on http://localhost:4000:
- Automatically discovers sibling
@m3rcena/wekyand@m3rcena/ecosubmodules using the Rust-style resolver and auto-mounts them! -
GET /health: Health status, mounted modules list, and server uptime. -
GET /dashboard/overview: Complete real-time overview of active game sessions, connected bots, and financial totals. -
WS /bridge: Real-time WebSocket connection for web dashboards, game move synchronization, and audio cues.
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