Skip to content
PartyKit Docs
GitHub Discord Twitter

Party.Server (Server API)

Party.Server

Each PartyKit server is a TypeScript module that implements the Party.Server interface.

// server.ts
import type * as Party from "partykit/server";
export default class Server implements Party.Server {}

Note: Previously, PartyKit supported an alternative export default {} satisfies PartyKitServer syntax. You can read the API documentation for the legacy syntax here

new Party.Server (constructor)

The Party.Server constructor receives an instance of Party.Party, which gives you access to the room state and resources such as storage, connections, id, and more.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  constructor(readonly party: Party.Party) {
    // ...
  }
}

Party.Server.options

You can define an options field to customise the PartyServer behaviour.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  readonly options = {
    hibernate: false,
  };
}
Party.Server.options.hibernate

Whether the PartyKit platform should remove the server from memory between HTTP requests and WebSocket messages. The default value is false.

Related guide: Scaling PartyKit Servers with Hibernation

Party.Server.onStart

Called when the server is started, before first onConnect or onRequest.

You can use this to load data from storage and perform other asynchronous initialization, such as retrieving data or configuration from other services or databases.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  async onStart() {}
}

Party.Server.onConnect

Called when a new incoming WebSocket connection is opened.

Receives a reference to the connecting Party.Connection, and a Party.ConnectionContext that provides information about the initial connection request.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  async onConnect(connection: Party.Connection, ctx: Party.ConnectionContext) {}
}

Related guide: Building a Real-time WebSocket server

Party.Server.onMessage

Called when a WebSocket connection receives a message from a client, or another connected party.

Receives the incoming message, which can either be a string or a raw binary ArrayBuffer, and a reference to the sending Party.Connection.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  async onMessage(message: string | ArrayBuffer, sender: Party.Connection) {}
}

Party.Server.onClose

Called when a WebSocket connection is closed by the client.

Receives a reference to the closed Party.Connection. By the time onClose is called, the connection is already closed and can no longer receive messages.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  async onClose(connection: Party.Connection) {}
}

Party.Server.onError

Called when a WebSocket connection is closed due to a connection error.

Receives a reference to the closed Party.Connection, and an Error object.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  async onError(connection: Party.Connection, error: Error) {}
}

Party.Server.onRequest

Called when a HTTP request is made to the party URL.

Receives an instance of Party.Request, and is expected to return a standard Fetch API Response.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  async onRequest(req: Party.Request) {
    return new Response(req.cf.country, { status: 200 });
  }
}

Related guide: Responding to HTTP requests

Party.Server.onAlarm

Called when an alarm is triggered.

Alarms have access to most Party resources such as storage, but not Party.id and Party.context.parties properties. Attempting to access them will result in a runtime error.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  async onAlarm() {}
}

Related guide: Scheduling tasks with Alarms

Party.Server.getConnectionTags

You can set additional metadata on connections by returning them from a getConnectionTags, and then filter connections based on the tag with Party.getConnections.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  getConnectionTags(
    connection: Party.Connection,
    ctx: Party.ConnectionContext
  ) {
    const country = (ctx.request.cf?.country as string) ?? "unknown";
    return [country];
  }
  async onMessage(message: string) {
    for (const british of this.party.getConnections("GB")) {
      british.send(`Pip-pip!`);
    }
  }
}

static onBeforeRequest

Runs before any HTTP request is made to the party. You can modify the request before it is forwarded to the party, or return a Response to short-circuit it.

Receives an instance of Party.Request, and is expected to either return a request, or a standard Fetch API Response.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  static async onBeforeRequest(
    req: Party.Request,
    lobby: Party.Lobby,
    ctx: Party.ExecutionContext
  ) {
    return new Response("Access denied", { status: 403 });
  }
}

Because the static onBeforeRequest method runs in an edge worker near the user instead of in the room, it doesn’t have access to Party room resources such as storage. Instead, you can access a subset of its properties via a Party.Lobby.

Related reading: How PartyKit works

static onBeforeConnect

Runs before any WebSocket connection is made to the party. You can modify the request before it is forwarded to the party, or return a Response to prevent the connection

Receives an instance of Party.Request, and is expected to either return a request, or a standard Fetch API Response.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  static async onBeforeConnect(
    req: Party.Request,
    lobby: Party.Lobby,
    ctx: Party.ExecutionContext
  ) {
    return new Response("Access denied", { status: 403 });
  }
}

Because the static onBeforeConnect method runs in an edge worker near the user instead of in the room, it doesn’t have access to Party room resources such as storage. Instead, you can access a subset of its properties via a Party.Lobby.

Related reading: How PartyKit works

static onFetch

Runs on any HTTP request that does not match a Party URL or a static asset. Useful for running lightweight HTTP endpoints that don’t need access to the Party state.

Receives an instance of Party.Request, and is expected to either return a standard Fetch API Response.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  static async onFetch(
    req: Party.Request,
    lobby: Party.FetchLobby,
    ctx: Party.ExecutionContext
  ) {
    return new Response(req.url, { status: 403 });
  }
}

Because the static onFetch method runs in an edge worker near the user instead of in the room, it doesn’t have access to Party room resources such as storage. Instead, you can access a subset of its properties via a Party.FetchLobby.

Related reading: Creating custom endpoints with onFetch

Party.Worker

The Party.Worker interface describes the static methods available on the Party.Server class. You can use it to add additional type safety to your TypeScript code:

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  static async onFetch(req: Party.Request) {
    return new Response(req.url);
  }
}

Server satisfies Party.Worker;

Party

Each Party.Server instance receives an instance of Party.Party as a constructor parameter, and can use it to access the room state and resources such as storage, connections, id, and more.

import type * as Party from "partykit/server";
export default class Server implements Party.Server {
  constructor(readonly party: Party.Party) {
    // ...
  }
}

Party.id

Party ID defined in the Party URL, e.g. /parties/:name/:id.

Party.internalID

Internal ID assigned by the platform. Use Party.id instead.

Party.env

Environment variables defined for this party.

Related reading: Managing environment variables with PartyKit.

Party.storage

A per-party, asynchronous key-value storage.

  • The key must be a string with a max size of 2,048 bytes.
  • The value can be any type supported by the structured clone algorithm, limited to 128 KiB (131,072 bytes) per value
// write arbitrary data
const input = { username: "jani" };
await this.party.storage.put("user", { user });
// read data
const user = await this.party.storage.get<{ username: string }>("user");

Related reading: Persisting state into storage.

Party.context

Additional information about other resources in the current project.

Party.context.parties

Access other parties in this project.

const otherParty = this.party.context.parties.other;
const otherPartyInstance = otherParty.other.get("room-id");
const req = await otherRoom.fetch({ method: "GET" });
const res = await req.json();

Read more: Using multiple parties per project

Party.broadcast

Send a message to all connected clients, except connection ids listed in the second array parameter.

this.party.broadcast(message, [sender.id]);

Related guide: Building a Real-time WebSocket server

Party.getConnection

Get a connection by connection id. Returns a PartyConnection undefined if connection by id doesn’t exist.

Party.getConnections

Get all currently connected WebSocket connections. Returns an iterable list of PartyConnections.

Optionally, you can provide a tag to filter returned connections.

const playerCount = [...this.party.getConnections()].length;
for (const everyone of this.party.getConnections()) {
  everyone.send(`Let's play!`);
}
for (const tagged of this.party.getConnections("some-tag")) {
  tagged.send(`You're it!`);
}

Use PartyServer.getConnectionTags to tag the connection when the connection is made.

Party.Connection

Wraps a standard WebSocket, with a few additional PartyKit-specific properties.

connection.send("Good-bye!");
connection.close();
Party.Connection.id

Uniquely identifies the connection. Usually an automatically generated GUID, but can be specified by the client by setting an id property on PartySocket.

Party.Connection.uri

The original URI of the connection request.

Party.Connection.setState

setState allows you to store small pieces of data on each connection.

Unlike Party.storage, connection state is not persisted, and will only exist for the lifetime of the WebSocket connection.

connection.setState({ username: "jani" });
Party.Connection.state

Read state stored with Party.Connection.setState.

const user = connection.state?.username;
Party.Connection.serializeAttachment

Deprecated. Use Party.Connection.setState instead.

Party.Connection.deserializeAttachment

Deprecated. Use Party.Connection.state instead.

Party.Request

Wraps an underlying Cloudflare runtime Request.

Party.Lobby

Provides access to a limited subset of room resources for onBeforeConnect and onBeforeRequest methods.

Party.Lobby.id

See: Party.id

Party.Lobby.env

See: Party.env

Party.Lobby.parties

See: Party.context.parties

Party.FetchLobby

Provides access to a limited subset of project resources for the onFetch method:

Party.Lobby.env

See: Party.env

Party.Lobby.parties

See: Party.context.parties