Skip to content

Installation and Setup

M3rcena edited this page Nov 2, 2026 · 1 revision

πŸ“¦ @m3rcena/bridge Installation & Environment 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.


⚑ System Requirements

  • Node.js: >= 22.0.0 (LTS 22, 24, 26).
  • Dependencies: Zero external dependencies for core Bridge; ws for real-time WebSocket server.

πŸ“₯ Option A: Standard NPM Installation

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 ws

πŸ¦€ Option B: Git Submodule & Local Hosting (Rust-Style Resolver)

If 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.

1. Add Submodule to your Git Repository

git submodule add https://github.com/M3rcena/m3rcena-bridge.git submodules/m3rcena-bridge
git submodule update --init --recursive

2. Zero-Config Runtime Auto-Registration

Add 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

How the Rust-Style Resolver Works:

  1. Local-First Discovery: Automatically scans ./submodules/m3rcena-bridge, ./vendor/m3rcena-bridge, ./packages/m3rcena-bridge, ./libs/m3rcena-bridge.
  2. Transparent Interception: Patches module resolution so import { M3rcenaBridge } from '@m3rcena/bridge' redirects seamlessly to your local submodule without changing your code.
  3. NPM Fallback: If the local submodule is absent, it falls back to standard node_modules/@m3rcena/bridge.
  4. Source vs Build: In TypeScript environments (tsx, ts-node), it automatically loads TypeScript sources directly.

3. TypeScript Path Mapping (tsconfig.json)

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());

4. Optional Resolver Configuration File (m3rcena.resolver.json)

{
  "submodulesDir": "./submodules",
  "preferSource": true,
  "packages": {
    "@m3rcena/bridge": "./submodules/m3rcena-bridge"
  }
}

Or via environment variable:

export M3RCENA_BRIDGE_PATH="./submodules/m3rcena-bridge"

πŸŒ‰ Standalone Local Hosting

@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 host

This starts the Bridge Gateway Server on http://localhost:4000:

  • Automatically discovers sibling @m3rcena/weky and @m3rcena/eco submodules 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.

Clone this wiki locally