API reference › @evolu/nodejs › createRelay

function createRelay(
  __namedParameters: NodeJsRelayConfig,
): Task<Relay, never, RelayDeps>;

Defined in: packages/nodejs/src/local-first/Relay.ts:123

Creates an Evolu Relay server resource using Node.js.

Use createRelayDeps to create dependencies for better-sqlite3, or provide a custom SQLite driver implementation.

The relay serves each connection's requests one at a time, in order, and serves other connections between them. It does not read a connection while its requests wait, and it serves a request only after the previous reply is written to the connection, so a client that sends requests faster than it reads the replies is slowed down instead of growing the relay's memory. A request waiting for an asynchronous isOwnerWithinQuota holds the later requests of its connection, which the relay meanwhile neither reads nor pings, so the callback should settle quickly. One answer makes a bounded number of storage reads, so one request holds the relay only briefly. Limit connections per IP address in a reverse proxy in front of the relay.

For uptime monitors and container health checks, the relay answers GET and HEAD requests for /health with status 200 and {"status":"ok"} while its database file can be read, and with status 503 and {"status":"error"} otherwise. Other plain HTTP requests get status 426, because the relay serves only WebSocket connections.

Example

import { assertType, Port, type Task } from "@evolu/common";
import type { Relay } from "@evolu/common/local-first";
import { createRelay, type RelayDeps } from "@evolu/nodejs";

const main = createRelay({
  port: Port.orThrow(4000),
  isOwnerWithinQuota: (_ownerId, requiredBytes) => requiredBytes <= 1024 * 1024,
});

assertType<typeof main, Task<Relay, never, RelayDeps>>();