Getting Started

This guide will help you get started with IOServer quickly and efficiently.

Installation

Install IOServer using npm or yarn:

npm install ioserver
# or
yarn add ioserver
# or
pnpm add ioserver

Requirements

  • Node.js: >= 18.0.0

  • TypeScript: >= 5.0.0 (for TypeScript projects)

Basic Setup

1. Create Your First Server

import { IOServer } from 'ioserver';

const server = new IOServer({
  host: 'localhost',
  port: 3000,
  verbose: 'INFO',
});

await server.start();
console.log('🚀 Server running at http://localhost:3000');

2. Add a Service (Real-time)

Services handle WebSocket connections and real-time events:

import { BaseService } from 'ioserver';

class NotificationService extends BaseService {
  async notify(socket: any, data: any, callback?: Function) {
    // Broadcast to all connected clients
    socket.broadcast.emit('notification', {
      message: data.message,
      timestamp: Date.now(),
    });

    if (callback) callback({ status: 'sent' });
  }
}

// Register the service
server.addService({
  name: 'notifications',
  service: NotificationService,
});

3. Add a Controller (HTTP)

Controllers handle HTTP requests with automatic route mapping:

import { BaseController } from 'ioserver';

class ApiController extends BaseController {
  async getStatus(request: any, reply: any) {
    reply.send({
      status: 'OK',
      timestamp: new Date().toISOString(),
      uptime: process.uptime(),
    });
  }

  async createUser(request: any, reply: any) {
    const userData = request.body;
    // Process user creation
    reply.status(201).send({
      id: 'user123',
      ...userData,
    });
  }
}

// Register the controller
server.addController({
  name: 'api',
  controller: ApiController,
});

4. Configure Routes

Create a JSON file to define HTTP routes (routes/api.json):

[
  {
    "method": "GET",
    "url": "/status",
    "handler": "getStatus"
  },
  {
    "method": "POST",
    "url": "/users",
    "handler": "createUser"
  }
]

Configuration Options

Server Options

interface IOServerOptions {
  host?: string; // Default: 'localhost'
  port?: number; // Default: 8080
  verbose?: LogLevel; // Default: 'ERROR'
  routes?: string; // Default: './routes'
  cors?: CorsOptions; // CORS configuration
  mode?: TransportMode[]; // Socket.IO transports
  cookie?: boolean; // Enable cookies
}

CORS Configuration

const server = new IOServer({
  cors: {
    origin: ['http://localhost:3000', 'https://yourdomain.com'],
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
    credentials: true,
  },
});

Transport Modes

const server = new IOServer({
  mode: ['websocket', 'polling'], // Default: both
});

Directory Structure

Organize your project like this:

my-ioserver-app/
├── src/
│   ├── services/
│   │   └── ChatService.ts
│   ├── controllers/
│   │   └── ApiController.ts
│   ├── managers/
│   │   └── DatabaseManager.ts
│   └── app.ts
├── routes/
│   ├── api.json
│   └── chat.json
├── package.json
└── tsconfig.json

Next Steps