@empellio/relay-client

Minimal relay client for a Go-based WebSocket relay. It can run as a CLI or as a Vite plugin to expose your local dev server via the relay.

Requires Node.js 18+.

Install

• CLI and plugin: npm i -D @empellio/relay-client

Defaults

• RELAY_URL: ws://relay.vladimirurik.dev/register
• SUBDOMAIN: none (relay chooses)

CLI Usage

• Run with flags:
  • npx empellio-relay-client --subdomain mysub --target http://localhost:5173
• Or with env:
  • RELAY_URL=ws://relay.example.com/register SUBDOMAIN=mysub TARGET_URL=http://localhost:5173 npx empellio-relay-client
• Behavior:
  • Connects to the relay, registers optional subdomain, keeps alive with pings.
  • Proxies incoming requests to TARGET_URL when set; otherwise replies with an echo JSON payload.
  • Reconnects with exponential backoff up to 10s.

Vite Plugin

• vite.config.ts:
  • import relay from '@empellio/relay-client'
  • plugins: [relay({ relayUrl: 'ws://relay.example.com/register', subdomain: 'mysub' })]
• Behavior:
  • On dev server start, determines the chosen port and launches the relay client with targetUrl set to http://localhost:<port>.
  • Stops the client when the dev server shuts down.
  • Options can be provided via plugin options or env vars RELAY_URL, SUBDOMAIN.

Programmatic API

• Import: import { startRelayClient } from '@empellio/relay-client'
• Start:
  • const ctl = startRelayClient({ relayUrl, subdomain, targetUrl, logger });
• Stop:
  • ctl.stop() to close the connection and end the reconnect loop.
• Options:
  • relayUrl: WebSocket register endpoint, for example ws://relay.example.com/register.
  • subdomain?: Preferred subdomain (optional; relay decides the final value).
  • targetUrl?: Local HTTP/HTTPS URL to proxy requests to. If omitted, the client replies with an echo JSON.
  • logger?: Custom logger (log, warn, error). Defaults to console.

Notes

• The client sends a keepalive ping every 15s and reconnects with backoff when disconnected.
• When used via the Vite plugin, your dev server must be reachable at http://localhost:<port>.
• Security: This is for development. Do not expose sensitive services through the relay.

Build

• Built with tsup to ESM and CJS with type declarations.
• Exports:
  • Package default export: Vite plugin
  • Named: startRelayClient
  • Binary: empellio-relay-client

Changelog

• 0.1.0: Initial CLI and plugin based on shared TypeScript relay client.