Documentation

npm install playsocketjs

import PlaySocket from "playsocketjs";

// Create a new instance
// Omit the ID to let the server pick one
const socket = new PlaySocket("unique-client-id", {
    endpoint: "wss://example.com/socket"
});

// Set up the event handlers you need
socket.onEvent("status", status => console.log(status));
socket.onEvent("error", error => console.error(error));
...

const clientId = await socket.init(); // Connect

// Create a new room
const roomId = await socket.createRoom();

// Optionally, with initial storage
const roomId = await socket.createRoom({
  players: [{ name: "Player-1", level: 35 }],
  latestPlayer: null,
});

await socket.joinRoom("room-id"); // Join an existing room

socket.destroy(); // Destroy the instance to leave

// Assign to useState(), $state(), reactive() etc. on update
const [reactiveVar, setReactiveVar] = useState({});
socket.onEvent("storageUpdated", storage => {
    setReactiveVar(storage);
});

<p>Players: {reactiveVar.players?.join(", ")}</p>

const currentState = socket.storage; // Read-only access

socket.updateStorage("players", "array-add-unique", { username: "Player4", level: 2 });
socket.updateStorage("latestPlayer", "set", "Player4");
socket.updateStorage("playerInfo", "set", { date: "22-6-2026" });
socket.updateStorage("playerInfo", "object-set-key", "color", "red")

console.log(socket.storage.players); // Log players array

await socket.sendRequest("my-request-name", { fact: "You can build traditional client-server logic like this." })

new PlaySocket(id?: string, options: PlaySocketOptions)

import PlaySocketServer from "playsocketjs/server";

// Path defaults to "/"
const server = new PlaySocketServer();

function shutdown() {
    server.stop(); // Gracefully disconnect all clients
    process.exit(0);
}

process.on("SIGINT", shutdown);
process.on("SIGTERM", shutdown);

import express from "express";
import http from "node:http";
import PlaySocketServer from "playsocketjs/server";

const app = express();
const httpServer = http.createServer(app);

// Create PlaySocket server with existing HTTP server
const playSocketServer = new PlaySocketServer({
  server: httpServer,
  path: "/socket"
});

// Start the server
httpServer.listen(3000, () => {
  console.log("Server running on port 3000");
});

function shutdown() {
    playSocketServer.stop(); // Gracefully disconnect clients
    process.exit(0);
}

process.on("SIGINT", shutdown);
process.on("SIGTERM", shutdown);

const server = new PlaySocketServer();

server.onEvent("storageUpdateRequested", ({ roomId, clientId, update, storage }) => {
    const { key, type, value, secondValue } = server.getUpdateDetails(update);

    // Block updates on all keys except for "players" and "chats"
    if (!["players", "chats"].includes(key)) return false;

    if (key === "chats") {
        if (type !== "array-add") return false; // Only allow adding chats
        if (typeof value !== "string") return false; // Only allow strings
    }
});

const server = new PlaySocketServer();

server.onEvent("requestReceived", async ({ roomId, clientId, name, data }) => {
    if (name === "add-player-request") {
        const players = server.getRoomStorage(roomId)?.players || [];

        // Returning false or string rejects sendRequest() on the client
        if (players.find(p => p.id === clientId)) return "Player already added!";

        server.updateRoomStorage(roomId, "players", "array-add", { id: clientId, timestamp: Date.now() });
    }
});

const authedClients = [];
const server = new PlaySocketServer();

server.onEvent("clientRegistrationRequested", async (clientId, data) => {
    try {
        // Your custom auth logic...
        // For example, data could contain a token
        authedClients.push(clientId);
    } catch (error) {
        return "Error occurred during auth."; // Blocks the registration
    }
});

server.onEvent("clientDisconnected", async (clientId) => {
    const removeIndex = authedClients.indexOf(clientId);
    if (removeIndex !== -1) authedClients.splice(removeIndex, 1);
});

new PlaySocketServer(options?: PlaySocketServerOptions)

const server = new PlaySocketServer({
    server: httpServer,
    path: "/socket",
    verifyClient: (info, callback) => {
        const forwarded = info.req.headers["x-forwarded-for"];
        const ip = forwarded ? forwarded.split(",")[0].trim() : info.req.socket.remoteAddress;
        if (isRateLimited(ip)) {
            return callback(false, 429, "Too Many Requests");
        }
        callback(true);
    }
});