Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Server
✓ import { Server } from 'colyseus';
✗ const { Server } = require('colyseus');
Colyseus recommends ESM `import` statements for Node.js 20+ environments. While CommonJS `require` might work in some configurations, ESM is the standard.
Room
✓ import { Room } from 'colyseus';
✗ const { Room } = require('colyseus');
The `Room` class is the fundamental building block for defining multiplayer game logic and state. Use ESM `import` for modern Node.js environments.
colyseus (Vite plugin)
✓ import { colyseus } from 'colyseus/vite';
✗ import { colyseus } from 'colyseus'; // Incorrect path
The Vite plugin for Colyseus is exposed via a subpath export. It must be imported specifically from `'colyseus/vite'`.
Schema
✓ import { Schema, type ArraySchema, type MapSchema } from '@colyseus/schema';
✗ import { Schema } from 'colyseus';
Schema-related classes and types for defining synchronized state are part of the separate `@colyseus/schema` package, not directly from the main `colyseus` package.
Demonstrates setting up a basic Colyseus server with a room and state definition within a Vite project using the official plugin, enabling integrated development.
import { defineConfig } from 'vite';
import { colyseus } from 'colyseus/vite';
import { Server, Room } from 'colyseus';
import { Schema, type } from '@colyseus/schema';
// Define your Room State using Colyseus Schema
class MyState extends Schema {
@type('string') message: string = 'Hello, Colyseus!';
}
// Define your Colyseus Room logic
class MyRoom extends Room<MyState> {
onCreate(options: any) {
this.setState(new MyState());
console.log('MyRoom created with options:', options);
this.onMessage('hello', (client, message) => {
console.log(`${client.sessionId} sent: ${message}`);
this.state.message = `${client.sessionId} says: ${message}`;
client.send('ack', `Server received: ${message}`);
});
}
onJoin(client: any, options: any) {
console.log(`${client.sessionId} joined MyRoom.`);
this.broadcast('player_joined', `${client.sessionId} has joined!`);
}
onLeave(client: any, consented: boolean) {
console.log(`${client.sessionId} left MyRoom (consented: ${consented}).`);
this.broadcast('player_left', `${client.sessionId} has left!`);
}
onDispose() {
console.log('MyRoom disposed.');
}
}
// Create a Colyseus Server instance
const gameServer = new Server();
gameServer.define('my_room', MyRoom);
export default defineConfig({
plugins: [
colyseus({
serverEntry: '/src/server/index.ts', // Adjust path to your server entry file
serveClient: true, // Serve client-side assets alongside the server
devServer: {
server: gameServer,
port: Number(process.env.COLYSEUS_PORT ?? 2567), // Default Colyseus port or env variable
},
}),
],
build: {
rollupOptions: {
external: ['@colyseus/tools'] // Example: Externalize if not bundling server tools
}
}
});
Debug
Known issues
breakingColyseus now requires Node.js version 20.x or higher. Projects running on older Node.js versions must upgrade their environment to ensure compatibility and correct execution.fixUpdate your Node.js installation to version 20.x or later. Ensure your deployment environment also meets this minimum requirement.
affects: >=0.17.0
gotchaReconnection behavior in `devMode` has been updated (since v0.17.13 for transports). The server now sends `MAY_TRY_RECONNECT` close codes instead of `FAILED_TO_RECONNECT` during HMR reloads. This allows the client SDK to retry reconnection attempts more gracefully in development.fixUpdate `@colyseus/sdk` to version 0.17.40 or higher to correctly interpret the new reconnection close codes during development. This improves the HMR experience.
affects: >=0.17.13 (transports), >=0.17.40 (sdk)
gotchaType inference for `client.http.*` methods in `@colyseus/sdk` was previously flawed, potentially incorrectly requiring `query` and `params` arguments on endpoints that did not declare them, especially when `strictNullChecks` was disabled in TypeScript.fixUpgrade `@colyseus/sdk` to version 0.17.40 or newer. This release includes fixes to the type definitions, resolving erroneous type inference issues.
affects: >=0.17.40 (@colyseus/sdk)
breakingA fix in `gracefullyShutdown` ordering (in `@colyseus/core` 0.17.41) ensures pending `allowReconnection()` deferreds are rejected before room states are cached. This guarantees `onLeave()` cleanup routines run prior to state caching, preventing stale player data in restored room states.fixReview any custom server shutdown or reconnection logic. While standard setups may not require code changes, this affects the sequence of events during graceful shutdown and room state management. Ensure `onLeave` handles client disconnections as expected.
affects: >=0.17.41 (@colyseus/core)
gotchaWhen using TypeScript with schema decorators (`@type()`), it's crucial to set `"experimentalDecorators": true` and `"useDefineForClassFields": false` in your `tsconfig.json` for proper property accessor definition, especially when targeting ES2022 or higher.fixAdd or verify these compiler options in your `tsconfig.json`:
```json
{
"compilerOptions": {
"experimentalDecorators": true,
"useDefineForClassFields": false
}
}
``` affects: *
Errors
Common errors & fixes
ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()
This error occurs when attempting to use CommonJS `require()` syntax to load a Colyseus module (or its dependencies) in a Node.js environment configured for ES Modules, or if the package itself is ESM-only. Colyseus increasingly favors ESM.
fixEnsure your project uses ES Module `import` statements (e.g., `import { Server } from 'colyseus';`). If you are running Node.js >= 20.x, it's recommended to set `"type": "module"` in your `package.json` for top-level ESM support. For TypeScript, configure `"module": "Node16"` or `"ES2022"` in `tsconfig.json`. TypeError: (0 , colyseus_vite_1.colyseus) is not a function
This typically indicates an incorrect import path for the Colyseus Vite plugin or a misuse of its export, often a default import when a named import from a subpath is expected.
fixVerify that the Vite plugin is imported from the correct subpath using named imports: `import { colyseus } from 'colyseus/vite';`. Property 'query' is missing in type '{}' but required in type 'ClientHttpRequestOptions'
This error arises from the incorrect type inference in `@colyseus/sdk` (fixed in 0.17.40) where `client.http` methods incorrectly mandated `query` or `params` even when not needed for the specific API endpoint.
fixUpdate the `@colyseus/sdk` package to version 0.17.40 or newer. This version contains type definition corrections that resolve this issue.
Error: seat reservation expired
This error means that the client failed to establish a connection to a reserved room within the allocated time. Common causes include the server being under heavy load, incorrect network configuration, or mixed Colyseus package versions (e.g., mixing 0.14.x and 0.15.x).
fixIncrease the `seatReservationTime` in your Colyseus server configuration to allow more time for clients to connect. Verify your server's network and scaling setup. Crucially, ensure all `@colyseus/*` packages in your `package.json` are consistent in their major/minor version (e.g., all `0.17.x`).
Audit
Dependencies
@colyseus/corerequiredCore server-side functionalities, required for the Colyseus server instance.
@colyseus/schemarequiredRequired for defining and synchronizing room state with binary delta compression.
@colyseus/authoptionalOptional package for authentication and authorization features.
@colyseus/redis-driveroptionalOptional Redis-backed room driver for scaling across multiple processes/servers.
@colyseus/redis-presenceoptionalOptional Redis-backed presence system for managing user presence across servers.
@colyseus/uwebsockets-transportoptionalOptional transport layer using uWS.js for high performance.
@colyseus/ws-transportoptionalOptional default WebSocket transport layer.
@colyseus/h3-transportoptionalOptional transport layer for h3 (e.g., Nuxt, Nitro) environments.
@colyseus/bun-websocketsoptionalOptional transport layer optimized for Bun runtime.
viteoptionalRequired for using the Colyseus Vite plugin for integrated development workflow.