Building Modern Backends with Kaapi: Introduction & Getting Started

#typescript #node #backend #framework

Kaapi: A flexible, extensible backend framework for modern APIs with messaging, documentation, and type safety built right in.

This series is written for backend developers who love TypeScript and can appreciate Hapi’s design philosophy.

What Is Kaapi?

Kaapi (@kaapi/kaapi) is a TypeScript-first backend framework built on top of Hapi.js.

It gives you a clean foundation for building modular, documented, and message-driven APIs without the boilerplate.

Think of it as Hapi, but with:

Type safety throughout
Messaging support (Kafka-ready)
Auto-generated OpenAPI & Postman docs
Built-in logging via Winston

So not "Yet again a new Nodejs framework this year!" in case your were thinking that (I know you did) but rather a practical evolution: the same trusted Hapi core, now supercharged.

It’s about cutting boilerplate, not reinventing the wheel.

⚙️ Installation

Install it from npm:

npm install @kaapi/kaapi

🚀 Your First Kaapi Application

Kaapi is built on Hapi, so everything you know from Hapi still works; but Kaapi adds higher-level ergonomics.

Here’s the simplest working server:

import { Kaapi } from '@kaapi/kaapi';

const init = async () => {
  const app = new Kaapi({
    port: 3000,
    host: 'localhost',
  });

  await app.listen();
  app.log('🚀 Server running at:', app.base().info.uri);
};

init();

app.listen() starts the server
app.base() gives access to the underlying Hapi server

Routing

Routing feels familiar, declarative and type-safe:

app.route({
  method: 'GET',
  path: '/',
}, () => 'Hello World!');

Want a custom 404? Just register an empty route config:

app.route({}, (req, h) => h.response('404 Not Found').code(404));

The {} route acts as a global catch-all; simple and intuitive.

Logging Made Easy

Kaapi comes with Winston out of the box.

app.log.silly('This is mindless');
app.log.debug('Debugging');
app.log.info('Server started');
app.log.warn('This is a warning');
app.log.error('Something went wrong');

Or define your own logger:

import winston from 'winston';
import { createLogger, Kaapi } from '@kaapi/kaapi';

const logger = createLogger({
  level: 'info',
  transports: [new winston.transports.Console()],
});

const app = new Kaapi({ logger });

Built-in API Documentation

Kaapi automatically generates OpenAPI + Postman docs.
Once your server runs, open:

/docs/api → Swagger UI
/docs/api/schema → OpenAPI JSON
/docs/api/schema?format=postman → Postman collection

Everything comes from your routes and Joi validations; no manual Swagger config.

Example route:

import Joi from 'joi';

app.route<{ Query: { name: string } }>({
  method: 'GET',
  path: '/',
  options: {
    description: 'Greet someone',
    tags: ['Index'],
    validate: {
      query: Joi.object({
        name: Joi.string()
          .trim()
          .default('World')
          .description('Optional name to personalize the greeting response'),
      }),
    },
  },
}, ({ query: { name } }) => `Hello ${name}!`);