@prsm/mesh-express

A simple adapter for running Mesh inside an existing Express + HTTP server.

This package wires up a MeshServer instance to handle WebSocket upgrades using the native upgrade event and exposes an optional Express middleware.

Installation

npm install @prsm/mesh-express

Usage

import express from "express";
import http from "http";
import createMeshMiddleware from "@prsm/mesh-express";

const app = express();
const server = http.createServer(app);

const { middleware, mesh } = createMeshMiddleware(server, {
  path: "/ws",
  redisOptions: { host: "localhost", port: 6379 },
});

app.use(middleware); // optional

mesh.registerCommand("echo", async (ctx) => {
  return `echo: ${ctx.payload}`;
});

server.listen(3000, () => {
  console.log("Server listening on port 3000");
});

What does the middleware do?

The middleware enables Express to recognize WebSocket upgrade requests and adds a .ws() method to the request object. While most upgrades are handled automatically by Mesh via the upgrade event, .ws() gives you manual control for custom upgrade logic (e.g. auth).

When to use .ws()

Use .ws() when you need to conditionally accept or reject WebSocket connections inside an Express route.

app.use("/ws", (req, res, next) => {
  if (!req.ws) return next();

  const token = req.query.token;

  if (!isValidToken(token)) {
    return res.status(401).send("Unauthorized");
  }

  const ws = await req.ws(); // manually upgrade

  ws.send("Upgraded!");
});

This is useful for:

• Auth checks during upgrade
• Inspecting query params or headers
• Rejecting based on app state (e.g. maintenance)

In most cases, you won't need .ws()—Mesh handles upgrades automatically if the request path matches, but the option is there when you need it.

API

createMeshMiddleware(server, options)

| Param | Type | Description | |-----------|------------------------|------------------------------------------| | server | http.Server | The existing HTTP server to attach to | | options | MeshServerOptions | Standard Mesh config (plus optional path) |

Returns an object with:

• middleware: an Express-compatible async middleware
• mesh: the MeshServer instance for command registration, etc.

Client usage

On the client, use the standard Mesh client:

import { MeshClient } from "@prsm/mesh/client";

const client = new MeshClient("ws://localhost:3000/ws");
await client.connect();

const res = await client.command("echo", "hello");
console.log(res); // "echo: hello"

Notes

• Defaults to using / as the WebSocket upgrade path if options.path is not specified.
• If the request does not match the configured path, the socket is rejected with HTTP 400.
• This package does not create a server—it binds Mesh to your existing one.

License

MIT