API Reference – pluv.io

Returns a PluvClient instance.

This is a re-export of createClient from @pluv/client.

Returns a CreateBundle instance.

Creates a bundle to be able to access the PluvClient from a react hook.

This is the bundle returned from createBundle.

Returns a CreateRoomBundle instance.

Creates a bundle to be able to access PluvRoom capabilities from various react hooks.

React provider component to allow the PluvClient created by createClient to be accessible in child components via usePluvClient. This is identical to importing the created client, so this is primarily useful for dependency injection when testing.

1<PluvProvider>{children}</PluvProvider>

Returns PluvClient.

Returns the PluvClient that was created via createClient.

This is the bundle returned from createRoomBundle.

React provider component to mock PluvRoomProvider. Enables hooks from CreateRoomBundle to work for single-player. This can be useful as in Storybook within a decorator when mocking PluvRoomProvider.

1import { y } from "@pluv/react";
2import { MockedRoomProvider } from "./io";
3
4<MockedRoomProvider
5    // Mock events sent and received for hooks in child components.
6    events={{
7        $EMIT_EMOJI: ({ emojiCode }) => ({
8            EMOJI_RECEIVED: { emojiCode },
9        }),
10    }}
11    // Set initial presence for the current user
12    initialPresence={{
13        selectionId: null,
14    }}
15    // Set initial storage for usePluvStorage
16    initialStorage={() => ({
17        messages: y.array([]),
18    })}
19    // Set the room id
20    room="my-mock-room"
21>
22    {children}
23</MockedRoomProvider>

React provider component to enable CreateRoomBundle hooks within child components. Mounting this component connects to a real-time room with other connected users. Unmounting this component will disconnect the room. See Create Rooms for more details.

1<PluvRoomProvider
2    // Set initial presence for the current user
3    initialPresence={{
4        selectionId: null,
5    }}
6    // Set initial storage for usePluvStorage
7    initialStorage={() => ({
8        messages: y.array([]),
9    })}
10    // Emits an error whenever authorization fails, for monitoring or
11    // debugging purposes
12    onAuthorizationFail={(error: Error) => {
13        console.error(error);
14    }}
15    // Set the room id
16    room="my-room-id"
17>
18    {children}
19</PluvRoomProvider>

Returns (event, data) => void.

Returns a broadcast function to emit an event and data to all connected clients. This is type-safe. The first parameter event will be the name of the event specified when creating your backend PluvIO instance and the second parameter data will be the associated response type. See Define Events for more details.

1const broadcast = usePluvBroadcast();
2
3broadcast("EMIT_RECEIVED", { emojiCode: 123 });

Returns WebSocketConnection.

Returns the websocket connection start of the current user.

1const connection = usePluvConnection();
2//    ^? const connection: {
3//        id: string | null;
4//        state: ConnectionState;
5//    }

Returns void.

Defines a listener for events broadcasted by connected clients. This is type-safe. The first parameter event is the name of the event to listen to from your backend PluvIO instance. The second parameter is a callback containing the data emitted from the broadcasted event.

1usePluvEvent("EMOJI_RECEIVED", ({ emojiCode }) => {
2    console.log(emojiCode);
3});

Returns [myPresence: TPresence | null, updatePresence: Function].

Returns the current user's presence, and a function to update the user's presence. Using this hook rerenders the component based on a deep-equality check on the user's presence value. This hook accepts a selector to return a modified presence to reduce rerenders.

1const { usePluvMyPresence } = createRoomBundle({
2    presence: z.object({
3        selectionId: z.nullable(z.string()),
4        selectionColor: z.string(),
5    }),
6});
7
8const [
9    // the user's presence
10    myPresence,
11    // a presence updater function
12    updateMyPresence
13] = usePluvMyPresence();
14
15// update individual base properties
16updateMyPresence({ selectionId: "name-input" });
17updateMyPresence({ selectionColor: "#123456" });
18
19// update multiple base properties
20updateMyPresence({
21    selectionId: "name-input",
22    selectionColor: "#123456",
23});
24
25// if you only need a partial presence
26const [myPresence] = usePluvMyPresence(({ selectionId }) => selectionId);
27
28// if you don't need presence, and just want the updater
29const [, updateMyPresence] = usePluvMyPresence(
30    // set selector to return a stable value
31    () => true
32);

Returns UserInfo | null.

Returns the user-info object for the current user. This hook accepts a selector to return a modified user-info to reduce rerenders.

1const myself = usePluvMyself();
2
3// if you don't need the entire user-info
4const myself = usePluvMyself(({ connectionId }) => connectionId);

Returns UserInfo | null.

Returns the user-info object for a connected user by connectionId string.

1const other = usePluvOther();
2
3// if you don't need the entire user-info
4const other = usePluvOther(({ connectionId }) => connectionId);

Returns readonly UserInfo[].

Returns all user-info objects for all connected users. This may trigger a lot of re-renders if presence updates frequently.

Note Consider using this hook only for deriving others' connectionId values to pass into usePluvOther.

1const others = usePluvOthers();
2
3// if you want to just pull out connectionId properties
4const connectionIds = usePluvOthers((others) => {
5    return others.map(({ connectionId }) => connectionId);
6});

Returns [TData | null, Yjs.SharedType | null].

Returns a base-level property of our yjs storage as a serialized value and a Yjs SharedType. The component is re-rendered whenever the Yjs SharedType is updated.

1import { y } from "@pluv/react";
2
3const { usePluvStorage } = createRoomBundle({
4    initialStorage: () => ({
5        messages: y.array(["hello"]),
6    }),
7});
8
9const [messages, sharedType] = usePluvStorage("messages");
10
11sharedType?.push(["world~!"]);
12
13messages?.map((message, key) => <div key={key}>{message}</div>);