Koritsu

A modern, type-safe file-based routing API framework for Bun with automatic OpenAPI documentation generation.

A powerful file-based routing system built with Bun, featuring automatic API documentation generation with Swagger UI.

Kōritsu (効率) means "efficiency" in Japanese, reflecting the framework's goal to streamline API development.

Features

• 🚀 File-based routing: Routes auto-discovered from filesystem structure
• 📁 Structured organization: A simple route.ts file per endpoint
• 📖 Auto-generated docs: Swagger UI with OpenAPI 3.1 specifications
• 🛡️ Type-safe validation: Built with TypeScript and Zod schemas
• 🔍 Health checks: Built-in health check endpoint
• ⚙️ Flexible configuration: Class options and environment variables

Quick Start

1. Install the package

bun install koritsu

2. Create the server entrypoint

// index.ts
import { Api } from "koritsu";

new Api({
  server: {
    routes: {
      dir: "./routes", // Directory containing your route files
    },
  },
}).start();

3. Create your first route

// routes/hello/route.ts
import { createRoute } from "koritsu";
import { z } from "zod";

export const GET = createRoute({
  method: "GET",
  handler: async () => {
    return Response.json({ message: "Hello, world!" });
  },
  spec: {
    responseFormat: "json",
    summary: "Hello World",
    responses: {
      200: {
        schema: z.object({
          message: z.string(),
        }),
      },
    },
  },
});

4. Run the server

bun run index.ts

Visit http://localhost:8080 to see your API documentation!

Documentation

📚 Complete Documentation

Example APIs

Check out the /examples directory for working API examples.

Publishing

The package is automatically published to NPM when changes are pushed to the main branch with automated:

• Coverage updates and badge generation
• Changelog generation using conventional commits
• NPM publishing with public access
• GitHub releases with generated release notes

License

This project is licensed under the MIT License. See the LICENSE file for details.