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