@bridgekit-uxlogic/relay

Protocol-proxy relay runtime for BridgeKit.

This package is the main public API for the backend/relay-first direction. It lets normal application drivers connect through approved BridgeKit relay ports instead of using package-specific BridgeKit adapters.

Install

npm install @bridgekit-uxlogic/relay

Create a project manifest

BridgeKit does not mutate your project during npm install. Generate the manifest explicitly:

npx bridgekit-relay init

The interactive wizard asks for:

• project name
• runtime: node, webcontainer, or bolt
• output path
• resource types to request
• resource IDs for MongoDB, PostgreSQL, MySQL, Redis, custom TCP, files, HTTP/HTTPS, or WebSocket

For scripted setup, use flags:

npx bridgekit-relay init --name stacktest --mongodb local-mongodb

Useful init flags:

npx bridgekit-relay init --mongodb local-mongodb --file uploads
npx bridgekit-relay init --postgres local-postgres --http local-api
npx bridgekit-relay init --tcp local-redis:6379:redis --websocket local-ws

The init command creates bridgekit.config.json, including requires capability declarations and relays[] entries for TCP driver-compatible services.

For StackBlitz/WebContainer projects, also generate the small browser companion and a root HTML template:

npx bridgekit-relay init --mongodb local-mongodb --webcontainer-assets

This creates:

• src/bridgekit-browser.js
• index.html

The generated frontend file only connects the browser companion transport. It does not contain database credentials, queries, or app business logic.

Start TCP relays from a manifest

import { connectAndStartTcpRelays } from '@bridgekit-uxlogic/relay';

const bridge = await connectAndStartTcpRelays({
  manifestPath: 'bridgekit.config.json',
  agentUrl: 'ws://localhost:7777/bridgekit'
});

console.log(bridge.relays.map((relay) => relay.url));

Manifest example

{
  "name": "driver-compatible-demo",
  "runtime": "node",
  "requires": {
    "services": [
      { "id": "local-mongodb", "type": "tcp", "permissions": ["stream"] }
    ]
  },
  "relays": [
    {
      "id": "mongo-driver-port",
      "type": "tcp",
      "resourceId": "local-mongodb",
      "protocol": "mongodb",
      "listen": { "host": "localhost", "port": 27017 },
      "options": { "keepAlive": true, "noDelay": true }
    }
  ]
}

Normal driver usage

import mongoose from 'mongoose';

await mongoose.connect(process.env.MONGODB_URI ?? 'mongodb://localhost:27017/stacktest');

WebContainer backend bridge

import { BridgeKitClient, startTcpRelaysFromManifest } from '@bridgekit-uxlogic/relay';
import { startWebContainerBridgeServer } from '@bridgekit-uxlogic/relay/webcontainer-node';
import manifest from './bridgekit.config.json' assert { type: 'json' };

const bridgeServer = await startWebContainerBridgeServer({ host: 'localhost', port: 8787 });
const bridgekit = new BridgeKitClient({ transport: bridgeServer.transport, manifest });

await bridgekit.connect();
await startTcpRelaysFromManifest({ manifest, client: bridgekit });

Browser companion:

import { createWebContainerRelayCompanion } from '@bridgekit-uxlogic/relay/webcontainer-browser';

createWebContainerRelayCompanion({ backendUrl: 'ws://localhost:8787/bridgekit-relay' });