Getting Started
Installation
Installing IOServer and configuring your TypeScript project.
Installation
Requirements
- Node.js ≥ 18
- TypeScript ≥ 5.0
- A
tsconfig.jsonwith strict mode and decorator support (see below)
Install the package
# npm
npm install ioserver
# pnpm
pnpm add ioserver
# yarn
yarn add ioserver
TypeScript configuration
IOServer requires a tsconfig.json that targets ES2020 or later and enables experimental decorators. The settings below mirror the configuration used by IOServer itself:
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"lib": ["ES2020"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"resolveJsonModule": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "**/*.test.ts"]
}
strict: true is intentional. IOServer is designed for strict TypeScript and all examples in this documentation assume strict mode is active.Running with ts-node (development)
Install ts-node as a dev dependency to run TypeScript files directly without a build step:
pnpm add -D ts-node @types/node
Then run your entry point:
npx ts-node src/index.ts
Project structure
A typical IOServer project looks like this:
src/
├── index.ts # Entry point — creates and starts IOServer
├── managers/
│ └── DatabaseManager.ts # Shared singletons
├── services/
│ └── ChatService.ts # WebSocket event handlers
├── controllers/
│ └── ApiController.ts # HTTP route handlers
├── watchers/
│ └── HealthWatcher.ts # Background tasks
├── middlewares/
│ └── AuthMiddleware.ts # HTTP / WS guards
routes/
└── api.json # Route declarations for ApiController
The routes/ directory (default: ./routes relative to process.cwd()) must contain one JSON file per controller, named after the controller.