Using the power of Durable Objects, this example shows website visitor locations in real-time. Anyone around the world visiting the demo website will be displayed as a dot on the globe! This template is powered by PartyKit.
Each time someone visits the page, a WebSocket connection is opened with a Durable Object that manages the state of the globe. Visitors are placed on the globe based on the geographic location of their IP address, which is exposed as a property on the initial HTTP request that establishes the WebSocket connection.
The Durable Object instance that manages the state of the globe runs in one location, and handles all incoming WebSocket connections. When a new connection is established, the Durable Object broadcasts the location of the new visitor to all other active visitors, and the client adds the new visitor to the globe visualization. When someone leaves the page and their connection is closed, the Durable Object similarly broadcasts their removal. The Durable Object instance remains active as long as there is at least one open connection. If all open connections are closed, the Durable Object instance is purged from memory and remains inactive until a new visitor lands on the page, opens a connection, and restarts the lifecycle.
In this template, only one Durable Object instance is created, since all visitors should see updates from all other visitors, everywhere in the world. A more complex version of this application could instead show a map of the country the visitor is located in, and only display markers for other visitors who are located in the same country. In this case, a Durable Object instance would be created for each country, and the client would connect to and receive updates from the Durable Object instance corresponding to the visitor's country.
For this example, Durable Objects are used for synchronizing but not storing state. Since visitor connections are ephemeral, and tied to the in-memory lifespan of the Durable Object instance, there's no need to use persistent storage. However, a more complex version of this application could display the all-time visitor count, which needs to be persisted beyond the in-memory lifespan of the Durable Object. In this case, the Durable Object code would use the Durable Object Storage API to persist the value of the counter.
Outside of this repo, you can start a new project with this template using C3 (the create-cloudflare
CLI):
npm create cloudflare@latest -- --template=cloudflare/templates/multiplayer-globe-template
A live public deployment of this template is available at https://multiplayer-globe-template.templates.workers.dev
- Install the project dependencies with a package manager of your choice:
npm install
- Deploy the project!
npx wrangler deploy