Universal Bridge: A Protocol for Local Services

Universal Bridge is a framework- and runtime-agnostic protocol for mounting a same-origin control plane for local companion processes.

Frameworks and runtimes expose different dev-server integration points—plugins, rewrites, middleware, and server APIs. Without a shared layer, each tool needs a separate integration for every host.

Universal Bridge mounts that shared layer at /__universal/*, providing HTTP health/state/control routes, WebSocket events, an optional runtime WebSocket gateway, and API proxying. Framework-specific adapters translate it for each host environment.

Who is this for?

Use Universal Bridge when you're building a developer tool—such as an overlay, panel, CLI companion, or local service—that needs to work across frameworks and server runtimes.

If you're using a tool that already includes Universal Bridge integration, configure that tool instead; you usually do not need to install Universal Bridge directly.

Table of Contents

• Installation
• What it provides
• Use cases
• Quick start (Vite)
• Core concepts
• Integration and runtime surfaces
• Public API reference
• Configuration
• Protocol summary
• Usage examples
• Architecture overview
• Design caveats
• Compatibility
• Additional docs

Installation

npm i universal-bridge

pnpm add universal-bridge

yarn add universal-bridge

bun add universal-bridge

What it provides

• same-origin bridge endpoints under /__universal/*
• runtime lifecycle control (start/restart require command; stop is idempotent)
• runtime status and capability reporting for UIs/automation
• websocket event stream with protocol versioning
• optional same-origin runtime WebSocket gateway
• /api/* passthrough proxy from host origin to runtime origin
• framework/server/build-tool adapter surfaces plus a preset API for tool packages

Non-goals:

• no first-party UI or hosted service
• no requirement that end users import UniversalBridge directly when a tool already wraps it

Use cases

• devtool overlays/sidebars/panels that should run across frameworks
• local CLIs/scripts that need runtime status and control via the same bridge
• internal developer platforms that expose same-origin local control APIs

Quick start (Vite)

// vite.config.ts
import { createUniversalVitePlugin } from "universal-bridge/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    createUniversalVitePlugin({
      command: "node",
      args: ["./scripts/dev-runtime.js"],
    }),
  ],
});

Core concepts

• Bridge path prefix: defaults to /__universal.
• Runtime helper: optional process manager for your tool runtime command.
• Protocol version: current bridge protocol is 2 (universal.v2+json for negotiated event sockets).
• Preset API: recommended integration API for tool authors so users configure one entry point (mytool().vite(), mytool().next(...), etc.).

Integration and runtime surfaces

| Surface | Import path | | ------------------------------------------------------------------------------------------ | ------------------------------ | | Vite-based dev servers (React, Vue, Solid, SvelteKit, Remix, TanStack Start, Vinext, etc.) | universal-bridge/vite | | Next.js | universal-bridge/next | | Nuxt | universal-bridge/nuxt | | Astro | universal-bridge/astro | | Angular CLI proxy flow | universal-bridge/angular/cli | | Bun.serve | universal-bridge/bun | | Node middleware + HTTP server | universal-bridge/node | | Express middleware | universal-bridge/express | | Fastify | universal-bridge/fastify | | Hono on Node server | universal-bridge/hono | | webpack-dev-server | universal-bridge/webpack | | Rsbuild dev server | universal-bridge/rsbuild | | Rspack dev server | universal-bridge/rspack | | Docker Compose runtime helper for adapters that manage a process | universal-bridge/docker |

Public API reference

Primary exports

| API | Import | | ------------------------------------------- | --------------------------------- | | createUniversalPreset | universal-bridge/preset | | createUniversalClient | universal-bridge/client | | createBridgeRuntimeStore | universal-bridge/client | | createClientRuntimeContext | universal-bridge/client-runtime | | createDockerComposeRuntime | universal-bridge/docker | | attachUniversalToExpress | universal-bridge/express | | startStandaloneUniversalBridgeServer | universal-bridge | | createUniversalBridge / UniversalBridge | universal-bridge |

The root package resolves to a browser-only client surface in browser builds. Import server APIs from universal-bridge in server code, and import browser APIs explicitly from universal-bridge/client when that makes the boundary clearer.

Adapter naming conventions

• createUniversal*: build a plugin/module/integration instance.
• withUniversal*: wrap and return config.
• attachUniversalTo*: attach to an existing server.
• startUniversal*: start helper/standalone utilities.

For expanded API coverage (including lifecycle helpers, runtime-context utilities, and adapter-specific helper exports), see INTEGRATION_GUIDE.md.

Configuration

Most adapter APIs accept shared bridge/runtime options.

| Option | Type | Default | Notes | | -------------------------- | ------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------ | | bridgePathPrefix | string | "/__universal" | Normalized to stay rooted under /__universal. | | autoStart | boolean | true | Auto-start runtime on state, proxy, events, and runtime WebSocket gateway paths. | | command | string | none | Required for managed runtime start/restart. | | args | string[] | [] | Runtime command args. | | cwd | string | process.cwd() | Runtime working directory. | | env | Record<string, string \| undefined> | none | Extra runtime environment variables. | | host | string | "127.0.0.1" | Runtime host binding. | | healthPath | string | "/api/version" | Runtime health probe endpoint. | | startTimeoutMs | number | 15000 | Runtime startup timeout. | | runtimePortEnvVar | string | "UNIVERSAL_RUNTIME_PORT" | Env var populated with selected runtime port. | | fallbackCommand | string | "universal dev" | Returned in some runtime-control error payloads. | | eventHeartbeatIntervalMs | number | 30000 | WS heartbeat for stale client cleanup. | | runtimeWebSocketGateway | { path: string } | none | Opt-in gateway at /runtime/ws to one managed runtime WebSocket path. | | instance | { id: string; label?: string } | none | Optional instance metadata in bridge state/health. | | additionalRewriteSources | string[] | [] | Extra path prefixes proxied directly to the runtime by adapters that support direct passthrough. |

Preset-specific options (createUniversalPreset)

• identity (required): { packageName: string; variant?: string }
• composition: "registry" | "local"
• instanceId: stable suffix for multiple preset instances
• unsafeOverrides: advanced adapter identity overrides
• client.entries: self-initializing browser modules loaded in development by the Vite, Next.js, Nuxt, and Astro preset adapters

Protocol summary

With prefix /__universal (or /__universal/<namespaceId> for presets):

• GET /health
• GET /state
• GET /runtime/status
• POST /runtime/start
• POST /runtime/restart
• POST /runtime/stop
• WS /events
• WS /runtime/ws (when runtimeWebSocketGateway is configured)
• ANY /api/* proxied to runtime /api/*

Behavior highlights:

• Route matching is query-safe.
• GET /state, WS /events, WS /runtime/ws, and proxy requests may auto-start runtime when autoStart is enabled.
• POST /runtime/stop is idempotent and disables auto-start, including gateway-triggered auto-start, until start/restart.
• WS /events carries bridge protocol events only.
• WS /runtime/ws forwards one configured runtime WebSocket path without parsing app messages; runtime close/error affects only the paired gateway socket.
• Bridge-generated errors use { success: false, message, error } envelope.
• Proxied /api/* responses pass through status/headers/body (including non-2xx).

For normative protocol details, see PROTOCOL.md.

For adapter-specific snippets (Next keying, Bun/Node/Express/Fastify/Hono servers, Docker Compose runtime helpers, webpack/Rsbuild/Rspack, Astro/Nuxt, Angular CLI, and standalone bridge usage), see INTEGRATION_GUIDE.md.

Usage examples

Preset export for your tool package

import { createUniversalPreset } from "universal-bridge/preset";

export function myTool() {
  return createUniversalPreset({
    identity: { packageName: "mytool" },
    client: {
      entries: [{ module: "mytool/overlay" }],
    },
    command: "mytool",
    args: ["dev"],
    fallbackCommand: "mytool dev",
  });
}

Entries load once per page in development. Each can read its derived namespace and bridge prefix with resolveClientRuntimeContext("mytool/overlay"), then mount its own UI. See the integration guide for a complete example and multiple-instance constraints.

Next.js

// next.config.ts
import { myTool } from "mytool";

export default myTool().next({ reactStrictMode: true });

Vite (including Vinext)

// vite.config.ts
import { myTool } from "mytool";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [myTool().vite()],
});

Client SDK

import { createUniversalClient } from "universal-bridge/client";

const client = createUniversalClient({ namespaceId: "mytool" });
const state = await client.getState();
const runtimeSocket = new WebSocket(
  client.getRuntimeWebSocketUrl({ query: { session: "local" } }),
  ["mytool.v1"],
);

const unsubscribe = client.subscribeEvents((event) => {
  if (event.type === "bridge-state") {
    console.log(event.state.runtime.phase, event.state.revision);
  } else {
    console.error(event.error);
  }
});

unsubscribe();

Architecture overview

High-level internals:

• src/bridge/*: HTTP/WS routing, runtime control routes, proxying, event fanout.
• src/runtime/runtime-helper.ts: command lifecycle and health probing.
• src/adapters/*: framework/server/build-tool integration points.
• src/client/*: typed browser/Node client helpers.
• src/preset.ts + src/preset-registry.ts: preset composition and registry behavior.

For implementation details, see ARCHITECTURE.md.

Design caveats

• UniversalBridge does not ship a first-party UI.
• Runtime start/restart are unavailable when command is not configured.
• The runtime WebSocket gateway is opt-in, proxies only its configured runtime path, and forwards text/binary frames opaquely.
• /events is bridge-only; runtime/app WebSocket traffic belongs on /runtime/ws.
• The bridge does not reconnect runtime WebSockets, replay application traffic, or interpret application messages.
• bridgePathPrefix is normalized under /__universal.
• Package is ESM-only ("type": "module").

Compatibility

• Runtime targets: Node.js and Bun.
• Package format: ESM-only ("type": "module").

Additional docs

• INTEGRATION_GUIDE.md: end-to-end guide for tool authors, adapter cookbook, and expanded API coverage.
• PROTOCOL.md: normative bridge contract.
• ARCHITECTURE.md: internal architecture.
• EXAMPLE.md: Universal Overlay setup and verification.

Docs checks:

bun run docs:lint
bun run docs:check