Sockress

Sockress is a socket-first Node.js framework built by Also Coder. It mirrors the Express API while automatically upgrading compatible requests to WebSockets — so Postman, curl and third-party HTTP clients keep working with zero changes, and realtime clients share the same routes and middleware.

We use Sockress internally for chat systems, live dashboards, notification engines and APIs that need both REST and realtime without maintaining two servers.

Why Sockress

Core features

• Express-style routing — app.get, app.post, app.put, app.patch, app.delete, app.head, app.options, app.all
• sockress.Router() — modular routers mounted with app.use('/api', router)
• Unified middleware — same pipeline for HTTP and WebSocket
• Automatic CORS — configurable origins, credentials, methods, headers
• Cookies — req.cookies and res.cookie()
• File uploads — createUploader() (multer-compatible), works on HTTP and socket
• Static files — serveStatic() and app.useStatic()
• Request context — req.context for passing data through middleware
• Response helpers — redirect(), sendFile(), download(), sendStatus(), format(), location(), vary()
• Validation — optional JSON Schema via Ajv (validate(schema), app.addSchema())
• Realtime events — app.emit(), app.on(), res.emitEvent() for socket broadcasts
• Graceful shutdown — hooks on beforeExit, SIGINT, SIGTERM

Installation

npm install sockress

Optional peers (install only when you need them):

npm install ajv      # JSON Schema validation
npm install multer   # file uploads

Sockress supports ESM and CommonJS:

// ESM
import { sockress, createUploader, serveStatic, Router } from 'sockress';

// CommonJS
const { sockress, createUploader, serveStatic, Router } = require('sockress');

Quick start

import { sockress } from 'sockress';

const app = sockress();

app.use((req, res, next) => {
  console.log(`[${req.method}] ${req.path}`);
  next();
});

app.get('/ping', (req, res) => {
  res.json({ ok: true, via: 'sockress' });
});

app.listen(5051, (err, address) => {
  if (err) throw err;
  console.log(`Sockress listening on ${address?.url}`);
});

Route params work like Express: req.params, req.query, req.body, req.cookies, req.file / req.files.

Routers & middleware

import { sockress, Router } from 'sockress';

const app = sockress();
const userRouter = Router();

userRouter.get('/', (req, res) => res.json({ users: [] }));
userRouter.get('/:id', (req, res) => res.json({ id: req.params.id }));
userRouter.post('/', (req, res) => res.json({ created: true }));

app.use('/api/users', userRouter);

Parameter middleware with app.param(), chainable routes with app.route(), and 4-argument error handlers — same patterns as Express.

Validation (optional)

With Ajv installed, pass a schema object before the handler:

app.post('/users', {
  schema: {
    body: {
      type: 'object',
      required: ['name', 'email'],
      properties: {
        name: { type: 'string' },
        email: { type: 'string', format: 'email' }
      }
    }
  }
}, (req, res) => {
  res.json({ id: 1, ...req.body });
});

Shared schemas via app.addSchema(). Response schema validation supported. Works on both HTTP and WebSocket transports.

Realtime events

Broadcast to all connected WebSocket clients:

app.emit('message', { hello: 'from server' });

Listen for client events:

app.on('message', (data, ctx) => {
  app.emitTo(ctx.socket, 'message', { echo: data });
});

Inside a socket route handler, reply on the same connection:

app.post('/ping', (req, res) => {
  res.emitEvent('pong', { ok: true });
  res.json({ ok: true });
});

File uploads & static files

import { sockress, createUploader, serveStatic } from 'sockress';

const app = sockress();
const uploader = createUploader({
  dest: './uploads',
  limits: { fileSize: 2 * 1024 * 1024 }
});

app.post('/avatar', uploader.single('avatar'), (req, res) => {
  if (!req.file) return res.status(400).json({ error: 'avatar missing' });
  res.json({ path: req.file.path });
});

app.use('/uploads', serveStatic('./uploads', { stripPrefix: '/uploads' }));

Configuration

const app = sockress({
  cors: {
    origin: ['http://localhost:3000'],
    credentials: true
  },
  socket: {
    path: '/sockress',
    heartbeatInterval: 30_000,
    idleTimeout: 120_000
  },
  bodyLimit: 1_000_000,
  logging: 'info' // false | 'error' | 'warn' | 'info' | 'debug'
});

Companion client

Pair with sockress-client for automatic socket transport, FormData serialization and HTTP fallback:

import { sockressClient } from 'sockress-client';

const api = sockressClient({ baseUrl: 'http://localhost:5051' });
const response = await api.post('/api/auth/login', {
  body: { email: 'user@example.com', password: 'secret' }
});

When to use Sockress

• Live dashboards and admin panels with push updates
• Chat, notifications and presence systems
• APIs that must accept both REST webhooks and realtime clients
• Greenfield Node backends where you want Express ergonomics plus sockets

Built by Also Coder

Sockress powers realtime features in projects we ship for clients. Need integration help, a custom backend or a full product built on Sockress? Use the form on this page — we reply within one working day.

Links

• npm: sockress
• GitHub: github.com/alsocoders/sockress
• Issues & PRs: welcome on GitHub