v4

.github/workflows/test.yml

@@ -12,17 +12,18 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        node: ['20.x', '22.x', '23.x', '24.x']
+        node: ['20.x', '22.x', '24.x']
         os: [ubuntu-latest, windows-latest]
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Install Node ${{ matrix.node }}
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v5
         with:
           node-version: ${{ matrix.node }}
+          cache: yarn
 
       - name: Install dependencies
         run: yarn

.gitignore

@@ -10,6 +10,9 @@ dist
 !.yarn/plugins
 !.yarn/sdks
 
+# Pagefind search index
+_pagefind/
+
 # Environment variables
 .env
 .env.local

.vscode/settings.json

@@ -1,3 +1,4 @@
 {
-	"editor.defaultFormatter": "esbenp.prettier-vscode"
+	"editor.defaultFormatter": "esbenp.prettier-vscode",
+	"typescript.tsdk": "node_modules/typescript/lib"
 }

.yarnrc.yml

@@ -1,2 +1,3 @@
 nodeLinker: node-modules
-yarnPath: .yarn/releases/yarn-4.5.0.cjs
+
+yarnPath: .yarn/releases/yarn-4.13.0.cjs

.zed/settings.json

@@ -0,0 +1,4 @@
+{
+	"formatter": "prettier",
+	"format_on_save": "on",
+}

apps/docs/mdx-components.tsx

@@ -0,0 +1,10 @@
+import {useMDXComponents as getDocsMDXComponents} from 'nextra-theme-docs';
+
+const docsComponents = getDocsMDXComponents();
+
+export function useMDXComponents(components?: Record<string, React.ComponentType>) {
+	return {
+		...docsComponents,
+		...components,
+	};
+}

apps/docs/next-env.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/docs/next.config.mjs

@@ -3,8 +3,7 @@
 import nextra from 'nextra';
 
 const withNextra = nextra({
-	theme: 'nextra-theme-docs',
-	themeConfig: './src/theme.config.tsx',
+	contentDirBasePath: '/',
 });
 
 export default withNextra({

apps/docs/package.json

@@ -1,28 +1,28 @@
 {
 	"name": "@kaito-http/docs",
 	"private": true,
-	"version": "3.2.1",
+	"version": "4.0.0-beta.33",
 	"author": "Alistair Smith <hi@alistair.sh>",
 	"license": "MIT",
 	"dependencies": {
-		"es-urlcat": "^1.0.0",
-		"next": "^15.1.4",
-		"nextra": "3.3.1",
-		"nextra-theme-docs": "3.3.1",
+		"next": "^15.3.3",
+		"nextra": "^4",
+		"nextra-theme-docs": "^4",
 		"pathcat": "^1.4.0",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0"
 	},
 	"scripts": {
 		"dev": "next",
 		"start": "next start",
-		"build": "next build"
+		"build": "next build && pagefind --site .next/server/app --output-path public/_pagefind"
 	},
 	"devDependencies": {
 		"@types/node": "^22.10.5",
 		"@types/react": "^19.0.5",
 		"@types/react-dom": "^19.0.3",
-		"typescript": "^5.7.3"
+		"pagefind": "^1",
+		"typescript": "5.9.2"
 	},
 	"description": "Functional HTTP Framework for TypeScript",
 	"homepage": "https://github.com/kaito-http/kaito",

apps/docs/src/app/[[...mdxPath]]/page.tsx

@@ -0,0 +1,23 @@
+import {generateStaticParamsFor, importPage} from 'nextra/pages';
+import {useMDXComponents as getMDXComponents} from '../../../mdx-components';
+
+export const generateStaticParams = generateStaticParamsFor('mdxPath');
+
+export async function generateMetadata(props: {params: Promise<{mdxPath?: string[]}>}) {
+	const params = await props.params;
+	const {metadata} = await importPage(params.mdxPath);
+	return metadata;
+}
+
+const Wrapper = getMDXComponents().wrapper!;
+
+export default async function Page(props: {params: Promise<{mdxPath?: string[]}>}) {
+	const params = await props.params;
+	const {default: MDXContent, toc, metadata, sourceCode} = await importPage(params.mdxPath);
+
+	return (
+		<Wrapper toc={toc} metadata={metadata} sourceCode={sourceCode}>
+			<MDXContent {...props} params={params} />
+		</Wrapper>
+	);
+}

apps/docs/src/app/layout.tsx

@@ -0,0 +1,48 @@
+import {Footer, Layout, Navbar} from 'nextra-theme-docs';
+import {Head, Search} from 'nextra/components';
+import {getPageMap} from 'nextra/page-map';
+import 'nextra-theme-docs/style.css';
+import type {ReactNode} from 'react';
+
+export const metadata = {
+	title: {
+		default: 'Kaito',
+		template: '%s — Kaito',
+	},
+	description: 'Kaito: An HTTP framework for TypeScript',
+	twitter: {
+		card: 'summary_large_image',
+		site: '@alistaiir',
+	},
+};
+
+export default async function RootLayout({children}: {children: ReactNode}) {
+	return (
+		<html lang="en" dir="ltr" suppressHydrationWarning>
+			<Head faviconGlyph="✦" />
+			<body>
+				<Layout
+					navbar={
+						<Navbar
+							logo={<span>Kaito</span>}
+							projectLink="https://github.com/kaito-http/kaito"
+							chatLink="https://discord.gg/PeEPDMKBEn"
+						/>
+					}
+					pageMap={await getPageMap()}
+					docsRepositoryBase="https://github.com/kaito-http/kaito/blob/main/apps/docs"
+					editLink="Edit this page on GitHub"
+					feedback={{labels: 'docs-feedback', content: 'Feedback'}}
+					footer={
+						<Footer>
+							An open-source project by <a href="https://alistair.sh">Alistair Smith</a>
+						</Footer>
+					}
+					search={<Search />}
+				>
+					{children}
+				</Layout>
+			</body>
+		</html>
+	);
+}

apps/docs/src/pages/documentation/_meta.ts → apps/docs/src/content/documentation/_meta.ts

@@ -3,8 +3,9 @@ import type {Meta} from 'nextra';
 const meta: Meta = {
 	context: 'Context',
 	routes: 'Routes',
-	routers: 'Routers',
-	handler: 'Handler',
+	'router-basics': 'Router Basics',
+	'advanced-routing': 'Advanced Routing',
+	pipes: 'Pipes',
 	client: 'Client',
 	streaming: 'Streaming',
 	'error-handling': 'Error Handling',

apps/docs/src/content/documentation/advanced-routing.mdx

@@ -0,0 +1,77 @@
+---
+title: Advanced Routing
+description: Learn about advanced routing features in Kaito, including router merging, params, and middleware patterns
+---
+
+import {Callout} from 'nextra/components';
+
+# Advanced Routing
+
+## Router Merging
+
+Routers can be merged, which brings one router's routes into another, with a prefix. This is incredibly useful for larger apps, for example when you have multiple versions of an API.
+
+```ts filename="api.ts"
+import {v1} from './routers/v1.ts';
+import {v2} from './routers/v2.ts';
+
+export const api = router.merge('/v1', v1).merge('/v2', v2);
+```
+
+All type information, route names, and correct prefixes are preserved during merging.
+
+## Router Parameters
+
+The `.params()` method lets you declare what URL parameters a router expects when it gets merged. Pass the param names as a type argument, like `.params<'userId'>()` — no runtime validation needed, params are always strings extracted from the URL. This only matters when the router is merged somewhere that provides those parameters.
+
+### Basic Parameters
+
+```ts
+// Declare that this router needs a userId parameter
+const userRouter = router.params<'userId'>().get('/', async ({params}) => {
+	// params.userId is guaranteed to exist and is a string
+	return {id: params.userId};
+});
+
+// This works - we're mounting at a path that provides userId
+const app = router.merge('/users/:userId', userRouter);
+
+// This would be a type error - we're not providing userId
+const badApp = router.merge('/users', userRouter);
+```
+
+### Nested Parameters
+
+Parameters become especially powerful with deeply nested routers:
+
+```ts
+// This router needs both userId and postId
+const commentsRouter = router.params<'userId' | 'postId'>().pipe(async (ctx, params) => {
+	const [user, post] = await Promise.all([db.users.findById(params.userId), db.posts.findById(params.postId)]);
+
+	if (!user || !post) {
+		throw new KaitoError(404, 'Not found');
+	}
+
+	return {
+		...ctx,
+		user,
+		post,
+	};
+});
+
+// This router provides postId and forwards userId
+const postsRouter = router.params<'userId'>().merge('/posts/:postId/comments', commentsRouter);
+
+// Finally, we provide userId at the top level
+const app = router.merge('/users/:userId', postsRouter);
+```
+
+<Callout>
+	You can only call `.params()` once on a router. Multiple calls will result in a type error to prevent breaking
+	existing routes.
+</Callout>
+
+## Pipes
+
+Kaito uses `.pipe()` instead of traditional middleware to transform context before routes run. Pipes are type-safe, composable, and chainable. See the dedicated [Pipes](/documentation/pipes) page for full documentation, including chaining, plugins, reusable routers, and advanced generic patterns.

apps/docs/src/pages/documentation/client.mdx → apps/docs/src/content/documentation/client.mdx

@@ -1,12 +1,12 @@
 import {Callout} from 'nextra/components';
 
+# Client
+
 <Callout>
 	The Kaito client is a recent addition to the Kaito ecosystem. It's still in the early stages of development. While we
-	think it's definitely stable, there may be missing features or unexpected behaviours.
+	think it's definitely stable, there may be missing features or unexpected behaviors.
 </Callout>
 
-# Client
-
 Kaito provides a strongly-typed HTTP client that seamlessly integrates with your Kaito server. The client supports all HTTP methods, streaming responses, and Server-Sent Events (SSE) out of the box.
 
 To ensure compatibility, always use matching versions of the client and server packages, as they are released together.
@@ -20,12 +20,9 @@ bun i @kaito-http/client
 Create a client instance by providing your API's type and base URL:
 
 ```ts filename="api/index.ts"
-const app = router().merge('/v1', v1);
+const app = router.merge('/v1', v1);
 
-const handler = createKaitoHTTPHandler({
-	router: app,
-	// ...
-});
+const handle = app.serve();
 
 export type App = typeof app;
 ```
@@ -68,8 +65,8 @@ await api.post('/v1/users/@me', {
 
 ### Non-JSON Responses
 
-For endpoints that return a `Response` instance, you must pass `response: true` to the request options. This is enforced for you at a compile time type level, so you
-can't accidentally forget to pass it. The option is needed so the runtime JavaScript doesn't assume the response is JSON.
+For endpoints that return a `Response` instance, you must pass `response: true` to the request options. This is enforced at a compile time type level, so you
+cannot accidentally forget to pass it. The option is needed so the runtime JavaScript does not assume the response is JSON.
 
 ```ts
 const response = await api.get('/v1/response/', {

apps/docs/src/content/documentation/context.mdx

@@ -0,0 +1,70 @@
+---
+title: Context
+description: Context is a way to pass common data to all routes
+---
+
+import {Callout} from 'nextra/components';
+
+# Context
+
+In Kaito, context is information shared across every single route. You provide it at the root of your application, and Kaito generates it on every single request.
+
+Below is an example of things that you could include, but it's really up to you and what you would find useful to include in your app.
+
+In the documentation about routers, you'll learn about how routers can create their own context for enabling powerful separation of concerns. See [Pipes](/documentation/pipes) for how to transform and enrich context per-router.
+
+<Callout>
+	Passing the request/response objects to context is ok, but we firmly recommend you read the
+	[routes](/documentation/routes) documentation for information on the Request/Response model.
+</Callout>
+
+```ts filename="context.ts"
+import {create} from '@kaito-http/core';
+import {db} from './db.ts';
+
+// Create a new router with context
+export const router = create({
+	getContext: async (req, head) => {
+		return {
+			req,
+			head,
+			time: new Date(),
+
+			searchForUser: async (query: string) => {
+				return await db.users.search(query);
+			},
+
+			// This is just an example
+			getSession: async () => {
+				const cookies = req.headers.get('cookie');
+
+				// this is bad code, use a cookie parser library! npmjs.com/package/cookie is a good one
+				const token = cookies
+					?.split(';')
+					.find(cookie => cookie.startsWith('token='))
+					?.split('=')[1];
+
+				return await db.sessions.findByToken(token);
+			},
+		};
+	},
+});
+```
+
+You can then use this context, when setup correctly with a router, inside every single route. E.g.
+
+```ts filename="routes/users.ts"
+import {k} from '@kaito-http/core';
+import {router} from '../context.ts';
+
+export const users = router.get('/users/search', {
+	query: {
+		search: k.string().max(200),
+	},
+
+	async run({ctx, query}) {
+		const users = await ctx.searchForUser(query.search);
+		return users;
+	},
+});
+```