🎉 pluv.io is now stable! Read our announcement here
DocsPricing
Dashboard

Create Client

Generally, it is recommended to use framework-specific bindings for your particular UI framework such as @pluv/react. However, if your selected framework is not yet supported, you can create a framework-agnostic pluv.io client to add automatic type-safe realtime to your app right away.

Installation

To install pluv.io for your framework-agnostic frontend, we will install the following packages from pluv.io:

PurposeLocationInstall command
Call and listen to events. Interact with shared storageClientnpm install @pluv/client
yjs CRDTBothnpm install @pluv/crdt-yjs

Installation Example

Here is an example installation for npm for you to copy:

# For the frontend
npm install @pluv/client
# Client peer dependencyes
npm install zod

# Optional if you wish to use CRDT storage
# For storage capatilities
npm install @pluv/crdt-yjs
# Storage peer dependencies
npm install yjs

Creating a PluvClient

Note: This example assumes that you've already created a backend pluv.io instance. Refer to the quickstart to learn more.

// frontend/io.ts

import { createClient, infer } from "@pluv/client";
import { yjs } from "@pluv/crdt-yjs";
import { z } from "zod";

// Use a type import to avoid including the code in your frontend
import type { ioServer } from "./server/pluv-io";

// Connect your `ioServer` type to the client via `infer`
// Note this is declared outside of `createClient` to workaround
// TypeScript inferrence limitations
const types = infer((i) => ({ io: i<typeof ioServer> }));
export const client = createClient({
    types,
    // Optional: Define the initial storage for rooms. This will set
    // the types for storage when using it in your application. Don't
    // worry about the value, as this can be overwritten when creating
    // a room via `client.createRoom`.
    initialStorage: yjs.doc((t) => ({
        messages: t.array<string>("messages", []),
    })),
    // Optional: Define your presence schema
    presence: z.object({
        selectionId: z.string().nullable(),
    }),

    // Optional: Provide additional data at the point of connecting to
    // to the room for use in `publicKey`, `wsEndpoint` or `authEndpoint`.
    // This is particularly useful for Cloudflare Pages where accessing
    // environment variables can be difficult
    metadata: z.object({
        secret: z.string(),
    }),

    // Required if you are using `@pluv/platform-pluv`: This is the
    // publishable-key that was created for your project on pluv.io
    publicKey: ({ metadata }) => "pk_...",

    // Optional: If a `publicKey` is provided, the `PluvRoom` will
    // automatically point to the pluv.io network. However, this
    // can be provided manually if you are self-hosting pluv.io
    wsEndpoint: ({ metadata, room }): string => {
        // Specify the ws endpoint to connect to 
        return `ws://localhost:3000/api/room?room=${room}`;
    },

    // Required if `authorize` was specified on `createIO`: This is
    // the endpoint where you've defined your own authorization
    // for your room's participants
    authEndpoint: ({ metadata, room }) => {
        // This can either return a url string, or an object
        // containing a url and options (fetch options) if
        // you need to customize the API request
        return `https://localhost:3000/api/pluv/auth?room=${room}`;
    },
});

Related