Get started with Kaito

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

You’ll also need a validation library, we recommend Zod as we support it with no extra work, but in theory you can use any validation library. Learn more about validation

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.

Quickstart Example

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

import {createUtilities} from '@kaito-http/core';
 
const serverStarted = Date.now();
 
export const {router, getContext} = createUtilities(async (req, res) => {
	// Our context object will include the request object and the server uptime.
 
	return {
		req,
		uptime: Date.now() - serverStarted,
	};
});

Secondly, we’ll need to create a 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 {createKaitoHandler} from '@kaito-http/core';
import {router, getContext} from './context.ts';
 
const app = router().get('/', async ({ctx}) => {
	return {
		uptime: ctx.uptime,
		time_now: Date.now(),
	};
});
 
// handle is typed as `(req: Request) => Promise<Response>
const handle = createKaitoHandler({
	// Pass our getContext function to the root server options
	getContext,
 
	// And pass our root router
	router: app,
 
	// Define an async `onError` handler, in case something goes wrong inside of the route.
	// More on that that later.
	onError: async ({error}) => {
		console.log(error);
 
		return {
			status: 500,
			message: error.message,
		};
	},
});
 
// 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