Skip to main content

@ttoss/http-server

Lightweight HTTP server built on Koa for the ttoss ecosystem.

Installation​

pnpm add @ttoss/http-server

Quick Start​

import { App, Router, bodyParser, cors } from '@ttoss/http-server';

const app = new App();

app.use(cors());
app.use(bodyParser());

const router = new Router();

router.get('/health', (ctx) => {
  ctx.body = { status: 'ok' };
});

app.use(router.routes());
app.use(router.allowedMethods());

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Health Check Endpoint​

Add a health check endpoint with a single line:

import { App, addHealthCheck } from '@ttoss/http-server';

const app = new App();

addHealthCheck({ app });
// or with custom path: addHealthCheck({ app, path: '/healthz' });

app.listen(3000);
// GET /health returns { status: 'ok' }

Core Features​

Route Parameters​

router.get('/users/:id', (ctx) => {
  const { id } = ctx.params;
  ctx.body = { userId: id };
});

Request Body Parsing​

JSON and form-urlencoded data are automatically parsed when using bodyParser():

router.post('/users', (ctx) => {
  const userData = ctx.request.body;
  ctx.body = { created: userData };
});

File Uploads​

import { multer } from '@ttoss/http-server';
import type { MulterFile } from '@ttoss/http-server';

const upload = multer();

router.post('/upload', upload.single('file'), (ctx) => {
  const file = ctx.file as MulterFile | undefined;
  ctx.body = {
    filename: file?.originalname,
    size: file?.size,
  };
});

Error Handling​

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (error) {
    ctx.status = error.status || 500;
    ctx.body = { error: error.message };
  }
});

API Reference​

All exports are re-exported from established Koa ecosystem packages:

  • App - Koa application
  • Router - Koa router for routing
  • bodyParser - Koa body parser for JSON/form parsing
  • cors - Koa CORS for cross-origin requests
  • multer - Koa multer for file uploads
  • addHealthCheck({ app, path? }) - Adds a health endpoint (defaults to /health) returning { status: 'ok' }
  • MulterFile (type) - File type for uploaded files