Get started with Kaito

bun i @kaito-http/core # Or use pnpm, npm, or yarn

You’ll need to use Zod for validation in your Kaito application.

Concepts

Kaito is very simple to use, it revolves around a few basic concepts:

Routes

A route is a single HTTP request handler. It accepts your context object, and returns a value that will be JSON encoded, or a Response object.

// Return a JSON value...
export const users = router.get('/users', async ({ctx}) => {
	return [
		{id: 1, name: 'John Doe'},
		{id: 2, name: 'Jane Bar'},
	];
});
 
// ...or return a Response object
export const images = router.get('/cool.png', async ({ctx}) => {
	return new Response(myImageBuffer, {
		headers: {'Content-Type': 'image/png'},
	});
});

Router

The router class holds all of our routes and their type information. Every app must have at least one router. Routers can be merged together, allowing you to organize them into different files by responsibility or whatever you want.

Context

Context is generated on every single request. It is up to you as the developer to decide what to place inside your context, but it will be available to access in every single route. For example, you could include a method to get the current user session, or a database connection, or anything else you want.

.onError()

The onError option is used to handle errors that are thrown inside of a route. It is a function that takes an error object and returns a status and message.

Quickstart Example

We first need to setup our router. You can put this in a router.ts file, for example.

import {create} from '@kaito-http/core';
 
const serverStarted = Date.now();
 
export const router = create({
	getContext: async (req, head) => {
		// Our context object will include the request object and the server uptime.
 
		return {
			req,
			uptime: Date.now() - serverStarted,
		};
	},
 
	// Define an async `onError` handler, in case something goes wrong inside of the route
	// This will handle all thrown errors EXCEPT for KaitoError, which is a special error type
	// you can throw for simple error messages with a status code
	onError: async error => {
		console.log(error);
 
		return {
			status: 500,
			message: error.message,
		};
	},
});

Secondly, we’ll need to create our main app router, our first route, and a handler function to accept requests from the runtime and/or server.

💡

We’re using Bun.serve() in this example, which is an API specific to the Bun runtime. The runtimes page will show you how to use Kaito with other runtimes like Node.js, Deno, etc.

import {router} from './router.ts';
 
const app = router.get('/', ({ctx}) => {
	return {
		uptime: ctx.uptime,
		time_now: Date.now(),
	};
});
 
// handle is typed as `(req: Request) => Promise<Response>
const handle = app.serve();
 
// Here we are using Bun.serve from the Bun runtime, but
// Kaito works with any runtime that supports the Fetch API
const server = Bun.serve({
	port: 4000,
	fetch: handle,
});
 
console.log(`Server is running on ${server.url}`);

Awesome! So we now have a server that can be accessed at http://localhost:4000 that mounts a GET route to / which will respond with the server’s uptime, and the time now.

Try it out by running bun src/index.ts and navigating to http://localhost:4000/.

Introduction Runtimes