Getting Started
Introduction
What is IOServer and when should you use it?
Introduction
IOServer is a TypeScript framework for building real-time backends. It wraps Fastify (HTTP) and Socket.IO (WebSocket) behind a structured component model that encourages clear separation of concerns.
What it does
- Combines HTTP and WebSocket in a single server instance
- Provides five component types — Services, Controllers, Managers, Watchers, and Middlewares — each with a well-defined role
- Wires components together through a typed AppHandle that gives every component access to shared state (managers) and the
send/logutilities - Auto-discovers WebSocket event handlers from public methods on Services
- Maps HTTP routes to Controller methods via JSON route files
- Ships with production-ready defaults: CORS, sensible error responses, optional SPA fallback
What it does NOT do
- It does not prescribe your storage layer — bring your own database manager
- It does not replace Socket.IO or Fastify — you get the full power of both, exposed via
appHandle.sendandthis.appHandlein controllers
Component model at a glance
┌──────────────────────────────────────────────────────────────┐
│ IOServer │
│ │
│ ┌───────────┐ ┌────────────┐ ┌──────────────────────┐ │
│ │ Manager │ │ Manager │ │ … │ │
│ │ (shared) │ │ (shared) │ │ │ │
│ └─────┬─────┘ └─────┬──────┘ └──────────────────────┘ │
│ │ │ │
│ └───────────────┴──── AppHandle ────────────────┐ │
│ │ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │ │
│ │ Service │ │ Controller │ │ │
│ │ (WebSocket events) │ │ (HTTP routes) │◄──┘ │
│ └──────────────────────┘ └──────────────────────┘ │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ Watcher │ │ Middleware │ │
│ │ (background tasks) │ │ (HTTP / WS hooks) │ │
│ └──────────────────────┘ └──────────────────────┘ │
└──────────────────────────────────────────────────────────────┘
| Component | Transport | Purpose |
|---|---|---|
| Service | WebSocket | Handles Socket.IO events (one method = one event) |
| Controller | HTTP | Handles Fastify routes (declared in JSON files) |
| Manager | — | Shared singleton available to all other components |
| Watcher | — | Long-running background tasks (intervals, polling) |
| Middleware | Both | Request/namespace guards, token validation, logging |
Technology stack
| Layer | Library | Version |
|---|---|---|
| HTTP server | Fastify | v5 |
| WebSocket | Socket.IO | v4 |
| CORS | @fastify/cors | v10 |
| Static files | @fastify/static | v9 |
| Language | TypeScript | ≥ 5.0 |
| Runtime | Node.js | ≥ 18 |