API Reference – pluv.io

Returns a PluvIO instance.

Creates a server-side PluvIO client that will create rooms to register your websockets to. Below will show a available configurations for createIO. To learn more about createIO, read Authorization, Cloudflare Workers, Node.js and PubSub.

1import { yjs } from "@pluv/crdt-yjs";
2import { createIO } from "@pluv/io";
3import { platformNode } from "@pluv/platform-node";
4import { z } from "zod";
5import { db } from "./db";
6
7const io = createIO({
8    // Optional: if provided, defines authorization for rooms created by io
9    authorize: {
10        // If required is false, users can authenticate for a room to
11        // attach an identity to their presence. Otherwise they will be
12        // anonymous.
13        required: true,
14        // The secret for generating your JWT
15        secret: process.env.PLUV_AUTH_SECRET!,
16        // The shape of your user object. `id` must always be required.
17        user: z.object({
18            id: z.string(),
19            // Here is an additional field we wish to add.
20            name: z.string(),
21        }),
22    },
23    // Specify to use Yjs CRDT for storage
24    crdt: yjs,
25    // Optional. Only needed to load persisted storage for rooms.
26    // Load storage for a newly created room.
27    getInitialStorage: async ({ room }) => {
28        const existingRoom = await db.room.findUnique({ where: { room } });
29
30        return existingRoom?.encodedState ?? null;
31    },
32    // Enable @pluv/io for Node.js
33    platform: platformNode(),
34    // Optional. Only needed for persisting storage for rooms.
35    // Before the room is destroyed, persist the state to a database
36    // to load when the room is re-created.
37    onRoomDeleted: async ({ encodedState, room }) => {
38        await db.room.upsert({
39            where: { room },
40            create: { encodedState, room },
41            update: { encodedState },
42        });
43    },
44    // It is unnecessary to save the storage state in this listener.
45    // If a room already exists, users will load the currently active
46    // storage before the storage from initialStorage.
47    onStorageUpdated: ({ encodedState, room }) => {
48        console.log(room, encodedState);
49    },
50});

This is the client returned by createIO.

Returns Promise<string>.

Creates a JWT for a user trying to connect to a room. This should be called within a custom authentication endpoint you define. See Authorization for more information.

1const token = await io.createToken({
2    room: "my-example-room",
3    user: {
4        id: "abc123",
5        name: "leedavidcs",
6    },
7});

Returns PluvIO.

Adds a new type-safe event to be broadcasted from PluvClient. See Define Events for more information.

1import { yjs } from "@pluv/crdt-yjs";
2import { createIO } from "@pluv/io";
3import { platformNode } from "@pluv/platform-node";
4import { z } from "zod";
5
6const io = createIO({
7    crdt: yjs,
8    platform: platformNode(),
9})
10    // When event "SEND_MESSAGE" is sent by the frontend and received
11    // on the server
12    .event("SEND_MESSAGE", {
13        // Define a zod validation schema for the input
14        input: z.object({
15            message: z.string(),
16        }),
17        // Emit a "MESSAGE_RECEIVED" from the server to the client
18        resolver: ({ message }) => ({ MESSAGE_RECEIVED: { message } }),
19    })
20    .event("EMIT_EMOJI", {
21        input: z.object({
22            emojiCode: z.number(),
23        }),
24        resolver: ({ emojiCode }) => ({ EMOJI_RECEIVED: { emojiCode } }),
25    });

Returns IORoom.

Retrieves a room by room name if it already exists. If the room doesn't already exist, the room is created and returned.

1const room = io.getRoom("my-example-room");

This is the room returned by PluvIO.getRoom. This is what websockets are registered to.

Returns void.

Broadcasts an event to all connected websockets to the room.

1room.broadcast("EMIT_EMOJI", {
2    emojiCode: 123,
3});

Type of string.

This is the id of the room, when the room was created.

1const roomId = room.id;

Returns Promise<void>.

Registers a websocket to the room. Accepts a secondary options parameter to pass-in a token for authorizing the room. Read Cloudflare Workers, Node.js and Authorization to learn more.

1// const token: string = ...
2
3room.register(webSocket, { token })