---
url: /backend/intro.md
description: >-
  KosmoJS API layer supports Hono, H3 and Koa frameworks, with elegant
  middleware composition, end-to-end type safety, and flexible route definitions
  inspired by Sinatra framework.
---

A source folder's API runs on one backend framework - **Hono**, **H3** or **Koa**.

* [Hono](https://hono.dev) - exceptional performance, runs unchanged on Node, Deno, Bun and edge platforms.
* [H3](https://h3.dev) - comparable performance and reach, built around Web standards.
* [Koa](https://koajs.com) - battle-tested Node ecosystem, elegant async/await middleware.

The decision matters less than it looks.
Route layout, middleware composition, payload validation, fetch clients, all behave identically whichever you pick.

What changes is the context object your handlers receive -
reading a body, setting a response, raising an error stay your framework's own idioms, untouched.

## What's in `api/`

Creating a source folder with a backend seeds a small, fixed set of files.
Each is a real source file you own - they are written once, never re-seeded.
What you import through `_/` is the opposite: derived into `var/lib/<folder>/`,
regenerated on every change, [never edited](/essentials/project-structure.md#path-mappings).

```text
src/<folder>/api/
├── app.ts                -> builds the backend app instance
├── server.ts             -> standalone server entry
├── dev.ts                -> dev-only hooks
├── errors.ts             -> the central error handler
├── use.ts                -> global middleware (every route in this folder)
├── env.d.ts              -> global context/state types, custom slots
│
└── users/                ── a route folder ──
    ├── use.ts            -> middleware for /users and everything under it
    ├── index.ts          -> the route  ->  /api/users
    ├── types.ts          -> colocated helper, NOT a route
    └── [id]/
        └── index.ts      -> the route  ->  /api/users/:id
```

### Foundation files

| File | What it is | When you touch it |
|---|---|---|
| `app.ts` | Builds the app with `appFactory()`, every route registered and each route file imported by the [first request](/dev-build-run/development-workflow.md#routes-load-on-first-request) to it. The callback hands you the **native** Hono/H3/Koa instance - this is where the error handler is registered and where [app middleware](/backend/middleware.md#app-middleware) or any framework plugin goes. It runs before the routes are registered, so a route added there takes the place of the route file with the same method and path. | Adding app middleware; enabling [debug](/dev-build-run/development-workflow.md#inspecting-api-routes) |
| `server.ts` | The standalone entry that boots `app.ts` - what `node dist/<folder>/api/server.js` runs in production. | Rarely |
| `dev.ts` | Dev-only: `devSetup(factory)`. The factory imports the app on the first API request and returns its `requestHandler`, the handler the dev server dispatches to (override it for WebSockets or custom dispatch), and its `teardownHandler`, run **before every reload** - close DB connections and sockets there or they leak across restarts. | Connections cleanup |
| `errors.ts` | The central error handler, registered by `app.ts`. The default distinguishes `ValidationError` and `HTTPError`, then content-negotiates JSON or plain text. | Customizing error responses |
| `use.ts` | [Global middleware](/backend/middleware.md) - runs for every route in this folder. | Request id, auth, permission checks |
| `env.d.ts` | Module augmentation for folder-wide types: `DefaultVariables`/`DefaultBindings` (Hono), `DefaultContext` (H3), `DefaultState`/`DefaultContext` (Koa), plus [custom slot names](/backend/middleware.md#slot-composition). | Typing `ctx.state` / bindings |

Only `app.ts` differs between backends, and only in how the error handler attaches:

#### Backend Overview | Foundation files | Hono

```ts
// Hono: api/app.ts
export default appFactory(({ app }) => {
  app.onError(defaultErrorHandler);
});
```

#### Backend Overview | Foundation files | H3

```ts
// H3: api/app.ts
export default appFactory(({ app }) => {
  app.use(onError(defaultErrorHandler));
});
```

#### Backend Overview | Foundation files | Koa

```ts
// Koa: api/app.ts
export default appFactory(({ app }) => {
  app.use(defaultErrorHandler);
});
```

### Inside a route folder

| File | What it is |
|---|---|
| `index.ts` | **The route.** Default-exports `defineRoute(...)`; its folder path becomes the URL. |
| `use.ts` | [Cascading middleware](/backend/cascading-middleware.md) for this folder and everything beneath it. Exports `UseT` to extend the typed context downward. |
| anything else | A colocated helper - schemas, types, queries, tests. Never a route, never scanned. |

`index.ts` and `use.ts` are the only two filenames the backend watcher acts on.
That is the whole convention: **one URL per folder, one file that defines it.**

Derived code - validators, the route table, fetch clients, the OpenAPI spec - never lands here.
It lives in `var/lib/`, is git-ignored, and you neither read nor edit it.
[Details ›](/essentials/why-codegen.md)

## Defining Endpoints

Every API route exports a `defineRoute` definition as its default export.
The factory function receives HTTP method builders and `use` for middleware,
and returns an array of handlers. Destructure only what you need:

```ts [api/users/[id]/index.ts]
import { defineRoute } from "_/api";

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    // handle GET /users/:id
  }),
]);
```

Multiple methods in one route:

```ts [api/users/index.ts]
export default defineRoute<"users">(({ GET, POST, PUT, DELETE }) => [
  GET(async (ctx) => { /* retrieve */ }),
  POST(async (ctx) => { /* create */ }),
  PUT(async (ctx) => { /* update */ }),
  DELETE(async (ctx) => { /* delete */ }),
]);
```

This method-based routing style draws inspiration from [Sinatra](https://sinatrarb.com/) -
the Ruby framework that pioneered it back in 2007.

Handler order doesn't matter - requests are dispatched by HTTP method.
Undefined methods return `405 Method Not Allowed` automatically.

Available builders: `HEAD`, `OPTIONS`, `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.

::: tip HEAD is served by your GET handler
`HEAD` is the one exception to the 405 rule. A route that defines `GET` but not `HEAD` still answers HEAD requests:
they are dispatched to the `GET` handler and validated against its schemas,
with the body dropped as the HTTP spec requires.
Define `HEAD` explicitly only when you want to override that.
Hono is the exception: its router ignores any `HEAD` handler you define,
so the fallback to `GET` always wins there.
:::

## The Route Name Type Argument

`defineRoute<"users/[id]">` restates the path the file already lives at, which looks redundant.

It isn't - and it's worth one minute to understand why, because it explains a lot of what follows.

The routing itself never needs it. The URL comes from the file's location, full stop.
The string is there for **TypeScript**, which cannot see the file system.

Everything KosmoJS knows about a route is placed into a `RouteMap` in `var/lib/`, keyed by route name:

```ts [var/lib/front/@api/routes.ts]
export type RouteMap = {
  "users/[id]": {
    paramsDefaults: [string],           // params, in path order
    paramsMappings: { id: 0 },          // name -> position
    cascadingState: UseT_apiUse & UseT_apiUsersUse,  // merged use.ts context
  },
  // ...every other route
};
```

The name is how the handler looks itself up in that map. That single lookup is what gives you:

* **`ctx.validated.params` typed** - which params exist, in what order, refined to what.
* **Cascading context typed** - the merged `UseT` of every `use.ts` above this route,
  which is why `ctx.get("user")` is typed without importing anything.
  [Details ›](/backend/cascading-middleware.md#type-safe-context-extension)
* **The params refinement tuple checked against the real params** - a tuple longer than
  the route has parameters is a compile error.

Because there is no runtime argument carrying it, TypeScript has nothing to infer it from -
so the type argument is **required**, and you write it once when the file is created.

In practice, you don't: the seeded [boilerplate](/backend/custom-templates.md) already contains the correct name.

::: tip What if it's wrong?
It can't silently drift. `defineRoute<R>` is constrained as `R extends keyof RouteMap`,
so a name that doesn't match a real route is a **compile error**, not a runtime surprise.

Rename `api/users/` to `api/people/` and the stale `defineRoute<"users/[id]">` fails to typecheck immediately -
the same refactor-as-a-checklist property the typed [Link](/frontend/link-navigation.md) component gives you on the frontend.
:::

The name is the route path **relative to `api/`**, without the trailing `index.ts` -
so `api/users/[id]/index.ts` is `"users/[id]"`, and `api/index/index.ts` is `"index"`.

Pages have no equivalent: a page component is an ordinary default export,
and its routing is resolved by the framework's own router, so there is nothing to look up.

## Where routes end up: `frontend.base` and `backend.base`

Each side of a source folder declares the URL prefix it owns, and each one is a **full path**.
The two are resolved independently:

```
API route URL  = join(backend.base, routeName)
page URL       = join(frontend.base, pagePath)
```

That is the one thing to hold on to; everything in the table follows from it.

| `frontend.base` | `backend.base` | API routes live at | pages live at | Note |
| --- | --- | --- | --- | --- |
| `/` | `/api` | `/api/<route>` | `/<page>` | app at the root |
| `/admin` | `/admin/api` | `/admin/api/<route>` | `/admin/<page>` | the API nested under the folder |
| `/admin` | `/api/v2` | `/api/v2/<route>` | `/admin/<page>` | nothing requires them to nest |
| none | `/api` | `/api/<route>` | none | an API-only folder |
| `/docs` | none | none | `/docs/<page>` | a pages-only folder |

Nesting the API under the pages prefix is a convention, not a rule -
useful when a folder should be relocatable as a unit, since moving `frontend.base`
means moving `backend.base` with it.

### An API-only folder

Omit `frontend` entirely and give the backend the prefix it should own:

```ts
// src/api/kosmo.config.ts
export default defineConfig({
  backend: {
    stack: "hono",
    base: "/api", // [!code hl]
  },
  validation: true,
});
// src/api/api/emails/index.ts  ->  /api/emails
```

The `api/` dir on disk never appears in the URL - it only separates server routes from `pages/`.

### How requests are dispatched

The dev server and the built `dist/run.js` route by prefix:
more specific prefixes win, and a folder's `backend.base` is ranked ahead of its `frontend.base` -
so `/front/api/users` reaches the API even though `/front` also matches.

A folder at `base: "/"` catches only what no other folder claims.
The server prints the prefix table on start; read it when a route lands somewhere unexpected:

```
  /admin/api   -> admin
  /api/        -> api
  /webhooks/   -> webhooks
  /admin       -> admin
  /            -> docs
```

## Type Safety

Parameters, payloads, and responses are all typed through type arguments -
the same definitions drive both compile-time checking and runtime validation.
No separate schema language, no DSL switching.
[Details ›](/backend/type-safety.md)

## Middleware

The `use` function gives you fine-grained middleware control at the route level,
complementing global and cascading middleware.
[Details ›](/backend/middleware.md)
