Node.js

pluv.io supports building real-time APIs with Node.js. You can define your handler and websocket server manually if you need more control, but if you'd like to get started quicky, check out createPluvHandler.

Using with Node.js (manual)

Let's step through how we'd put together a real-time API for Node.js.

Install dependencies

1# For the server
2npm install @pluv/io @pluv/platform-node
3
4# Server peer-dependencies
5npm install ws zod

Create PluvIO instance

Define an io (websocket client) instance on the server codebase:

1// backend/io.ts
2
3import { createIO } from "@pluv/io";
4import { platformNode } from "@pluv/platform-node";
5
6export const io = createIO({
7    platform: platformNode(),
8});
9
10// Export the websocket client io type, instead of the client itself
11export type AppPluvIO = typeof io;

Integrate PluvIO with ws

Integrate with ws on your Node.js server.

1// backend/server.ts
2
3import express from "express";
4import Http from "http";
5import WebSocket from "ws";
6import { io } from "./io";
7
8const PORT = 3000;
9
10const app = express();
11const server = Http.createServer();
12const wsServer = new WebSocket.Server({ server });
13
14const parseRoomId = (url: string): string => {
15    /* get room from req.url */
16};
17
18wsServer.on("connection", async (ws, req) => {
19    const roomId = parseRoomId(req.url);
20    const room = io.getRoom(roomId);
21
22    await room.register(ws);
23});
24
25server.listen(PORT, () => {
26    console.log(`Server is listening on port: ${port}`);
27});

createPluvHandler

If you don't need to modify your websocket server or handler too specifically, @pluv/platform-node also provides a function createPluvHandler to create a websocket server and handler for your automatically.

1import { createIO } from "@pluv/io";
2import { createPluvHandler, platformNode } from "@pluv/platform-node";
3import bodyParser from "body-parser";
4import cors from "cors";
5import express from "express";
6import Http from "http";
7import WS from "ws";
8
9const io = createIO({
10    platform: platformNode(),
11});
12
13const app = express();
14const server = Http.createServer(app);
15
16const Pluv = createPluvHandler({
17    // Your PluvIO instance
18    io,
19    // Optional: Specify the base path from which endpoints are defined
20    endpoint: "/api/pluv", // defaults to "/api/pluv"
21    // Your Http.Server instance
22    server,
23    // If your PluvIO instance defines authorization, add your authorization
24    // logic here. Return a user if authorized, return null or throw an error
25    // if not authorized.
26    async authorize({ req, res, roomId }) {
27        return {
28            id: "abc123",
29            name: "leedavidcs",
30        };
31    },
32});
33
34// Create your WS.Server instance, which listens to "connection" events
35const wsServer = Pluv.createWsServer();
36
37// Alternatively, define your own websocket server
38const wsServer = new WS.Server({ server });
39
40wsServer.on("connection", async (ws, req) => {
41    const { matched } = await Pluv.wsHandler(ws, req);
42
43    if (matched) return;
44
45    // didn't match with the Pluv handler, add your own logic
46    // ...
47});
48
49app.use(bodyParser.json());
50app.use(cors({ origin: "*" }));
51app.use(Pluv.handler);
52
53server.listen(3000);