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 PartyConnection
s.
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
Party.FetchLobby
Provides access to a limited subset of project resources for the onFetch
method:
Party.Lobby.env
See: Party.env