Kontas Web Framework for Bun

0.1.149 verified Sat Apr 25 auth: no javascript

Kontas is a minimalist and high-performance web framework designed specifically for the Bun JavaScript runtime. Currently at version 0.1.149, it focuses on providing a simple, Koa-style asynchronous middleware pipeline and routing for building web applications with Bun. Its core differentiator lies in its commitment to simplicity, speed, and native Bun integration, leveraging Bun's fast JavaScriptCore engine and built-in Web API compatibility. While its pre-1.0 version suggests a rapid release cadence with potential API evolution, Kontas aims to offer an elegant, developer-friendly experience for backend development, contrasting with more opinionated or heavier frameworks. It's ideal for projects prioritizing raw performance and a lightweight footprint within the Bun ecosystem, offering an alternative to frameworks like Elysia or Hono by emphasizing minimalism.

Common errors

error ReferenceError: require is not defined in ES module scope ↓

cause Attempting to use CommonJS `require()` syntax to import Kontas or other modules within a Bun project, which primarily uses ES Modules.

fix

Replace const Kontas = require('kontas'); with import Kontas from 'kontas';. Ensure all local files are also using ESM syntax or have .cts / .mts extensions if mixed modules are strictly necessary.

error Error: Port 3000 is already in use ↓

cause Another process is already listening on the specified port, preventing the Kontas server from starting.

fix

Change the port in app.listen(PORT, ...) to an available one (e.g., 8000), or terminate the process currently using the port (lsof -i :3000 on macOS/Linux, then kill <PID>).

error TypeError: Cannot read properties of undefined (reading 'response') ↓

cause Accessing `ctx.response` or other properties on a `Context` object that might be `undefined` or not correctly initialized, often due to an incorrect middleware signature or early access.

fix

Ensure middleware functions and route handlers correctly receive and pass the Context object. Verify the Context type definition and object structure in the Kontas documentation. Explicitly type ctx: Context to catch issues at compile-time.

Warnings

breaking As a 0.x.x version package, Kontas's API is subject to frequent and significant breaking changes without major version bumps. Always pin exact versions in `package.json` and review changelogs diligently. ↓

fix Consult the project's GitHub repository or NPM page for the latest API documentation before upgrading. Use `bun add kontas@<exact-version>`.

gotcha Kontas is built exclusively for Bun. It will not run on Node.js, Deno, or in a browser environment due to its reliance on Bun's specific runtime APIs and `Bun.serve` underneath. ↓

fix Ensure your project is configured to use Bun (e.g., `bun run <script>`). Do not attempt to run Kontas applications with `node`.

gotcha Error handling might differ from other popular web frameworks (e.g., Express, Koa). Understand Kontas's specific error propagation mechanism to prevent unhandled exceptions or unexpected responses. ↓

fix Review the Kontas documentation on error handling patterns. Implement global error middleware or specific try-catch blocks where necessary.

gotcha Body parsing for POST/PUT requests is not always built-in by default in minimalist frameworks. You might need to add specific middleware or handle it manually. ↓

fix Check Kontas's documentation for official body parsing middleware. If none exists, implement a custom middleware to parse JSON, form data, or other request bodies using Web Standard `Request` methods like `request.json()` or `request.formData()`.

Install

npm install kontas

yarn add kontas

pnpm add kontas

Imports

Kontas
wrong
```
const Kontas = require('kontas');
```
correct
```
import Kontas from 'kontas';
```
Kontas primarily uses ESM for Bun's native module system. CommonJS `require` is not supported for the main export.
Context
```
import type { Context } from 'kontas';
```
Import the `Context` type for type annotations in middleware and route handlers, enhancing type safety in TypeScript projects.
Middleware
```
import type { Middleware } from 'kontas';
```
Import the `Middleware` type for defining custom middleware functions with proper type signatures.

Quickstart

This quickstart sets up a basic Kontas server with a root GET route, a route with a path parameter, and a global middleware for logging requests. It demonstrates the core application setup and routing, highlighting TypeScript usage for context and middleware.

import Kontas from 'kontas';
import type { Context } from 'kontas';

const app = new Kontas();
const PORT = 3000;

// Basic GET route
app.get('/', (ctx: Context) => {
  return ctx.response.text('Hello, Kontas!');
});

// Route with a path parameter
app.get('/users/:id', (ctx: Context) => {
  const userId = ctx.params.id;
  return ctx.response.json({ message: `Fetching user ${userId}` });
});

// Middleware example
app.use((ctx: Context, next: () => Promise<void>) => {
  console.log(`[${new Date().toISOString()}] Request received: ${ctx.request.url}`);
  return next();
});

// Start the server
app.listen(PORT, () => {
  console.log(`Kontas server running on http://localhost:${PORT}`);
  console.log('Try visiting / and /users/123');
});