kaput

Zero-config graceful shutdown for Node.js

Stop writing 50+ lines of shutdown boilerplate. One import. Zero config. It just works.

---

Overview

This is the monorepo for kaput, containing:

• packages/kaput - The npm package
• apps/website - Landing page (coming soon)
• examples - Example projects

Quick Start

# Install dependencies
pnpm install

# Build everything
pnpm build

# Run dev mode for package
pnpm pkg:dev

# Run website locally
pnpm web:dev

# Run tests
pnpm test

Monorepo Structure

kaput/
├── packages/
│   └── kaput/              # npm package
│       ├── src/
│       │   ├── index.ts    # Public API + magic import
│       │   ├── kaput.ts    # Core class
│       │   ├── types.ts    # TypeScript types
│       │   ├── logger.ts   # Structured logger
│       │   ├── utils.ts    # Utility functions
│       │   ├── health.ts   # Health check middleware
│       │   └── resources/  # Resource handlers
│       │       ├── http.ts
│       │       ├── prisma.ts
│       │       ├── redis.ts
│       │       ├── bullmq.ts
│       │       └── generic.ts
│       └── tests/          # Unit tests
│
├── apps/
│   └── website/           # SvelteKit landing page
│       └── src/
│           ├── routes/
│           └── lib/
│               └── components/
│
└── examples/              # Example projects
    └── express-basic/

Usage

Magic Import (Zero Config)

import '@joint-ops/kaput';

import express from 'express';

const app = express();
app.listen(3000);

// kaput will automatically:
// ✅ Detect your HTTP server
// ✅ Handle SIGTERM/SIGINT signals
// ✅ Gracefully close connections
// ✅ Shut down in the correct order

Manual Registration

import { kaput } from '@joint-ops/kaput';

const server = app.listen(3000);
kaput.register(server);

// Register custom resources
kaput.register(prisma, { order: 100 });
kaput.register(redis, { order: 90 });

Features

• Zero Config - Just import and go
• Auto-detection - Finds HTTP servers, databases, caches automatically
• Correct Order - Shuts down in the right sequence
• Health Checks - Built-in /health and /healthz endpoints
• Type Safe - Full TypeScript support
• Production Ready - Designed for Kubernetes/Docker

Supported Resources

• HTTP servers (Express, Fastify, Node http/https)
• Databases (Prisma, Mongoose, Knex)
• Caches (Redis, ioredis)
• Queues (BullMQ)
• Generic closeables (anything with .close(), .disconnect(), etc.)

Available Commands

Root Commands

pnpm build          # Build all packages
pnpm dev            # Run all packages in dev mode
pnpm test           # Run all tests
pnpm test:run       # Run tests once
pnpm lint           # Lint all packages
pnpm clean          # Clean all build artifacts

Package Commands

pnpm pkg:build      # Build the kaput package
pnpm pkg:dev        # Watch mode for package
pnpm pkg:test       # Run package tests

Website Commands

pnpm web:dev        # Run website dev server (http://localhost:5173)
pnpm web:build      # Build website for production
pnpm web:preview    # Preview production build

Development

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0

Setup

# Clone the repo
git clone https://github.com/yourusername/kaput.git
cd kaput

# Install dependencies
pnpm install

# Build everything
pnpm build

# Run tests
pnpm test

Project Guidelines

• Use pnpm exclusively (no npm or yarn)
• Follow the existing code structure
• Write tests for new features
• Update TypeScript types
• Keep the README up to date

Documentation

Visit kaput.jointops.dev for full documentation (coming soon).

License

MIT - see LICENSE for details.

---

Built with ❤️ for the Node.js community