kontas

library0.1.149jsnpmunverified

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.

web-framework

npm install kontas

package ↗

INSTALL

IMPORT

SIG · KONTAS

kontas

web-frameworkjavascriptv0.1.149

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Kontas

✓ import Kontas from 'kontas';

✗ const Kontas = require('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.

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'); });

Debug

Known issues

breakingAs 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>`.

affects: >=0.1.0

gotchaKontas 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`.

affects: >=0.1.0

gotchaError 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.

affects: >=0.1.0

gotchaBody 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()`.

affects: >=0.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

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: Port 3000 is already in use

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>`).

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

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.

Upgrade

Version history

0.1.149latest on npm

Audit

Dependencies

typescriptrequiredPeer dependency, strongly recommended for type-safe development, as Kontas leverages Bun's native TypeScript support.

Agent activity

4 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/kontas ↗