---
url: /essentials/project-structure.md
description: >-
  The anatomy of a KosmoJS project - source folders, the derived lib directory,
  build output, and the reserved @/ ~/ _/ path mappings.
---

A KosmoJS project has four top-level directories, and each one has exactly one job.
Once that clicks, the rest of the docs read much faster.

```txt
my-app/
├── package.json          -> project settings: distDir, devPort, previewPort, scripts
├── tsconfig.json         -> minimal config, add paths to `include` to have them typechecked
│
├── src/                  ✍️  YOU WRITE THIS
│   ├── front/            ->   one source folder
│   └── admin/            ->   another, fully independent
│
├── lib/                  🤖 DERIVED - never edit
│   ├── tsconfig.json     ->   base config the root tsconfig extends
│   ├── front/            ->   derived code for src/front
│   └── admin/            ->   derived code for src/admin
│
├── dist/                 📦 BUILD OUTPUT
│   ├── run.js            -> runs every folder, one process
│   ├── front/
│   └── admin/
│
└── var/                  🗑️  Vite cache - disposable
```

The rule of thumb: **you own `src/`, KosmoJS owns `lib/`.**
Every `_/` import you write points into `lib/`.

## Inside a Source Folder

A source folder is a self-contained app. This is one with a Hono backend and a React frontend,
with SSR enabled - the fullest shape:

```txt
src/front/
├── kosmo.config.ts       -> what this folder is
├── tsconfig.json         -> { "extends": "../../lib/front/tsconfig.json" }
├── index.html            -> Vite's HTML entry
├── app.tsx               -> global wrapper, wraps EVERY route
├── router.ts             -> routerFactory: routes -> native router
│
├── api/                  ── server side ───────────────────────────
│   ├── app.ts            -> the backend app instance (appFactory)
│   ├── server.ts         -> standalone server entry
│   ├── dev.ts            -> dev hooks: requestHandler, teardownHandler
│   ├── errors.ts         -> THE central error handler
│   ├── use.ts            -> global middleware (runs for every route)
│   ├── env.d.ts          -> global context/state types, custom UseSlots
│   └── users/
│       └── [id]/
│           ├── index.ts  -> the route  ->  /api/users/:id
│           └── types.ts  -> colocated helper, NOT a route
│
├── pages/                ── client side ───────────────────────────
│   ├── 404.tsx           -> rendered for unmatched routes
│   ├── index/
│   │   └── index.tsx     -> the route  ->  /
│   └── users/
│       ├── layout.tsx    -> wraps everything under /users
│       └── [id]/
│           └── index.tsx -> the route  ->  /users/:id
│
├── components/
│   └── Link.tsx          -> type-safe navigation component
│
└── entry/
    ├── client.ts         -> mount / hydrate in the browser
    └── server.ts         -> renderToString / renderToStream  (SSR only)
```

Things worth noticing:

* **`api/` and `pages/` are siblings** with parallel trees,
  so an endpoint and its page are always one folder apart.
  Neither directory name appears in a URL.
* **Only `index.*` is a route.** Everything else in a route folder is a colocated helper.
  [Rationale ›](/routing/rationale)
* **`app.*` is not a layout.** It sits at the folder root and wraps every route;
  `layout.*` files live inside `pages/**/*` and wrap a subtree.
  [Details ›](/frontend/layouts#global-layout-via-app-file)
* **`use.ts` is not a route either.** Drop one in any `api/` folder and it wraps that subtree.
  [Details ›](/backend/cascading-middleware)

A folder created with `--no-backend` simply has no `api/`;
one created with `--no-frontend` has no `pages/`, `app.*`, `router.ts`, `index.html` or `entry/`.

## Inside `lib/`

You never edit `lib/`, but knowing what lives there makes the `_/` imports legible.
This is a React + Hono folder; exact filenames vary by framework,
while the `_/` names you import stay the same:

```txt
lib/
├── tsconfig.json         -> shared base for the root tsconfig
├── .gitignore            -> why lib/ is NOT in the root .gitignore
└── front/
    ├── tsconfig.json     -> this folder's jsxImportSource + path mappings
    ├── api.ts            -> _/api          defineRoute, use
    ├── api:factory.ts    -> _/api:factory  appFactory, devSetup, errorHandlerFactory
    ├── app.tsx           -> _/app          the AppProvider seam
    ├── router.tsx        -> _/router       routerFactory, createRouters
    ├── query.ts          -> _/query        TanStack client (when enabled)
    ├── use.ts            -> _/use          framework hooks (Vue/Svelte/MDX)
    ├── entry/
    │   ├── client.ts     -> _/entry/client
    │   └── server.ts     -> _/entry/server
    ├── fetch/            -> _/fetch        typed clients + ResponseT
    └── @api/
        └── routes.ts     -> the RouteMap
```

::: tip `lib/` has its own `.gitignore` - don't add it to the root one
The root `.gitignore` deliberately leaves `lib/` alone,
because `lib/.gitignore` handles it more precisely:
it ignores **everything** except `cache.json` and `types.ts` at any depth.

So derived code is *not* committed - it is a build artifact.
What is committed is the per-route derivation cache
(`cache.json`, keyed by content hashes of the route file and its type dependencies),
so a fresh clone or a CI run doesn't pay for a full rebuild.

Adding `lib/` to the root ignore file would drop that cache and make every clone slow.
:::

Deleting `lib/` is safe but not free: it forces a full rebuild,
which on a large project takes minutes. [Details ›](/validation/performance#when-it-becomes-noticeable)

## Path Mappings

Three prefixes are reserved. Don't reuse them for your own aliases.

| Prefix | Resolves to | Use it for |
|---|---|---|
| `@/*` | project root | anything shared across source folders - db layer, domain types |
| `~/*` | **this** source folder | your own modules inside the folder |
| `_/*` | `lib/<this folder>/` | derived code |

```ts
import { db } from "@/db";                    // my-app/db.ts
import type { User } from "~/types/user";     // src/front/types/user.ts
import { defineRoute } from "_/api";          // lib/front/api.ts
import fetchClients from "_/fetch";           // lib/front/fetch/
```

`~/` and `_/` are **folder-relative**: the same `_/api` in `src/admin` resolves to `lib/admin/api.ts`.
That is what keeps folders isolated - `admin`'s route names and navigation types never leak into `front`.

`@/` is how folders share without packages. Put a type in `db/models.ts`,
import it as `@/db/models` from every folder, change it once, and every folder sees it -
no workspaces, no publishing, no version bumps.

## Build Output

```txt
dist/front/
├── api/
│   ├── app.js            -> the app instance, for custom mounting
│   └── server.js         -> ready-to-run API server
├── client/
│   ├── assets/           -> hashed JS, CSS, images
│   └── index.html
└── ssr/                  -> only when SSR is enabled
    ├── app.js
    ├── server.js         -> serves pages AND the API
    ├── assets/           -> hashed, served at <base>/assets/
    └── public/           -> copy of public/, served at <base>/
```

The simplest way to run all of this is `node dist/run.js`, which dispatches across every folder in one process.
[Details ›](/dev-build-run/building-for-production#one-entry-point-for-the-whole-project)

Folders can also be deployed separately, in which case what you deploy depends on the folder's rendering mode -
and for SSR folders it is **not** everything in the directory.
[Details ›](/dev-build-run/building-for-production#what-to-deploy)

## Multiple Folders

The point of the whole layout. Three apps, one install, one set of types/helpers:

```txt
src/
├── marketing/    MDX,  no backend,   base "/"
├── app/          React + Hono,       base "/app"
└── admin/        Vue   + H3,         base "/admin"
```

Each has its own `kosmo.config.ts`, its own routes, middleware, layouts and build.
They share one `package.json`, one `node_modules`, and one `@/` root.

```sh
pnpm dev                  # all folders
pnpm dev app              # just one
pnpm build admin          # build one, deploy it independently
```

[Configuration reference ›](/essentials/config) · [Why source folders ›](/about)

---

---
url: /essentials/config.md
description: >-
  Complete reference for kosmo.config.ts - the frontend, backend and validation
  blocks, base URLs, stack plugins and vite options, and the project-level
  settings in package.json.
---

Every source folder owns a `kosmo.config.ts`. It is the one file that decides what that folder *is* -
which frameworks it runs, where it is served from, and what gets built for it.

```txt
my-app/
├── package.json                    <- project-level settings
└── src/
    ├── front/
    │   └── kosmo.config.ts         <- this folder's config
    └── admin/
        └── kosmo.config.ts         <- independent of front's
```

There is no project-wide `kosmo.config.ts`, and no `vite.config.ts`:
each side of the folder carries its own `viteConfig`.

## The Shape

The config is declarative - you describe what the folder has:

```ts [src/app/kosmo.config.ts]
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  frontend: {
    stack: "react", // or solid, vue, svelte, mdx
    base: "/",
    fetch: true,
    ssr: true,
    ssg: false,
    tanstack: { query: false },
  },
  backend: {
    stack: "hono", // or h3, koa
    base: "/api",
  },
  validation: true,
});
```

Three top-level keys, all optional: `frontend`, `backend`, `validation`.
A folder can have both sides, or just one.

Every feature key follows the same pattern: a plain value turns it on with defaults,
or an object turns it on and hands KosmoJS the instance to use -
`stack` takes a `plugin`, `ssr` / `ssg` / `fetch` / `validation` take a `generator`.

`defineConfig` turns that description into the right set of generators, in the right order,
and is the only import a folder config needs.

## frontend

### frontend.stack - required

`"react"` · `"solid"` · `"vue"` · `"svelte"` · `"mdx"`

A bare name runs that stack's Vite plugin with defaults:

```ts
stack: "react"
```

To configure it, construct the plugin yourself and pass it alongside the name:

```ts
import react from "@vitejs/plugin-react";

stack: {
  name: "react",
  plugin: react({ jsxRuntime: "automatic" }),
}
```

`name` is what KosmoJS routes on - which stack runs, which page extensions it watches,
the `jsxImportSource` it writes into your tsconfig.
`plugin` is handed to Vite as you built it, alongside anything KosmoJS adds for that stack.

The default plugin each stack resolves to:

| stack | default plugin |
|---|---|
| react | `@vitejs/plugin-react` |
| solid | `vite-plugin-solid` |
| vue | `@vitejs/plugin-vue` |
| svelte | `@sveltejs/vite-plugin-svelte` |
| mdx   | `@mdx-js/rollup`, with a basic set of `remarkPlugins` |

Bring your own plugin instance:

```ts
import mdx from "@mdx-js/rollup";

stack: {
  name: "mdx",
  plugin: mdx({
    remarkPlugins: [frontmatterPlugin, mdxFrontmatterPlugin],
    rehypePlugins: [rehypeSlug],
  }),
}
```

::: warning Don't also list the plugin in `viteConfig.plugins`
Whichever form you use, the plugin reaches Vite through `stack`.
Adding it to `viteConfig.plugins` as well runs the transform twice.
:::

### frontend.base - required

The URL prefix this folder's pages are served from. Must be absolute:

```ts
base: "/"          // app at the root
base: "/admin"     // admin dashboard under /admin
```

Duplicate slashes are collapsed and a trailing slash is stripped,
so `"/admin/"` and `"//admin"` both resolve to `"/admin"`.
Path traversal segments (`../`, `/./`) are rejected at startup.

### frontend.fetch

Typed [fetch clients](/fetch/intro) in `_/fetch`.

```ts
fetch: true
```

Clients are derived from the backend's routes, so this only produces anything
when the folder also has a `backend`.

### frontend.ssr

[Server-side rendering](/frontend/server-side-render).
Accepts `true`, or an options object:

```ts
ssr: true

ssr: {
  renderMode: {
    "docs/**": "stream",
  },
}
```

**`renderMode`** - `"string"` (default), `"stream"`, or a glob map for per-route selection.
[Details ›](/frontend/server-side-render#selecting-the-render-mode)

### frontend.ssg

[Static site generation](/frontend/static-site-generation).

```ts
ssg: true
```

Renders routes to static HTML at build time. Requires `ssr: true` -
the scaffolder turns SSR on for you when you ask for SSG.
Dynamic routes declare their variants with `staticParams`.

### frontend.tanstack

```ts
tanstack: { query: true }
```

Deploys the `_/query` runtime, swaps `_/app` for a provider that supplies the query client,
and gives each SSR request its own client. [Details ›](/frontend/tanstack-query)

### frontend.templates

Overrides seeded page boilerplate by route pattern:

```ts
templates: {
  "landing/*": landingTemplate,
  "marketing/**": landingTemplate,
}
```

[Custom Page Templates ›](/frontend/custom-templates)

### frontend.viteConfig

Vite's `UserConfig` for the client build - `plugins`, `resolve`, `css`, `server`, `define`, `optimizeDeps`, and the rest:

```ts
frontend: {
  stack: "react",
  base: "/",
  viteConfig: {
    plugins: [tailwindcss()],
    resolve: {
      alias: { "#shared": "/src/shared" },
    },
    css: {
      preprocessorOptions: { scss: { api: "modern" } },
    },
  },
}
```

A handful of Vite keys are **not** accepted, because KosmoJS derives them from the source-folder layout:
`root`, `base` (the folder's prefixes come from `frontend.base` / `backend.base`),
`cacheDir`, `mode`, `builder`, `future`, `legacy`.

## backend

### backend.stack - required

`"hono"` · `"h3"` · `"koa"`

A bare name, or the same object form the frontend takes.
The backend stacks have no Vite plugin, so the object carries only `name` today and the bare name is the usual form.
Vite settings for the API build go in [viteConfig](#backend-viteconfig).

### backend.base - required

The URL prefix this folder's API routes are served from - a **full path**,
resolved on its own rather than against `frontend.base`:

```ts
frontend: { base: "/vue" },
backend:  { base: "/vue/api" },   // routes at /vue/api/<route name>
```

Nesting it under the frontend base is the convention the scaffolder follows,
but nothing requires it - the two prefixes are independent:

```ts
frontend: { base: "/admin" },
backend:  { base: "/api/v2" },    // routes at /api/v2/<route name>
```

A route's final URL is `backend.base` + route name:

```
base "/api"        route "users/[id]"  ->  /api/users/:id
base "/admin/api"  route "users/[id]"  ->  /admin/api/users/:id
base "/v1"         route "users/[id]"  ->  /v1/users/:id
```

The `api/` directory name never appears in the URL - it separates server routes from `pages/` on disk, nothing more.

### backend.openapi

Derives an [OpenAPI 3.1 spec](/openapi) from this folder's routes. Options are required:

```ts
backend: {
  stack: "hono",
  base: "/api",
  openapi: {
    outfile: "openapi.json",
    openapi: "3.1.0",
    info: { title: "My API", version: "1.0.0" },
    servers: [{ url: "https://api.example.com/api" }],
  },
}
```

[Details ›](/openapi#configuration)

### backend.alias

Maps a public URL to an existing named route:

```ts
alias: {
  "/feed.xml": "rss",             // /feed.xml handled by the "rss" route
  "/members/[id]": "users/[id]",  // param names must match exactly
}
```

The key is absolute and is *not* prefixed by the router's base.
If it carries dynamic segments, their names must match the target route's parameters exactly, or the request 404s.

[Details ›](/backend/aliases)

### backend.templates

Overrides the seeded route boilerplate by route-name pattern -
the route file (`defineRoute(...)`), not a page component.
This is what makes it useful for seeding CRUD endpoints across many tables at once.

```ts
templates: {
  "admin/**": adminRouteTemplate,
}
```

[Details ›](/backend/custom-templates)

### backend.viteConfig

Vite's `UserConfig` for the API build, with the same exclusions as the frontend's:

```ts
backend: {
  stack: "hono",
  base: "/api",
  viteConfig: {
    define: { __API_BUILD__: true },
  },
}
```

The two sides are built separately, so `frontend.viteConfig` and `backend.viteConfig` are independent.

## validation

Runtime [validators derived from your types](/validation/intro).
Only meaningful alongside a `backend` - it validates incoming requests.

```ts
validation: true
```

For anything beyond on/off, pass an options object instead:

```ts
validation: {
  // override validation messages - node:util.format placeholders
  validationMessages: {
    STRING_MIN_LENGTH: "must be at least %d character%s long",
    NUMBER_MULTIPLE_OF: "must be a multiple of %s",
  },

  // file whose default export maps custom TypeBox types
  customTypesImport: "@/validation/types.ts",

  // identifier used for runtime refinements, default "VRefine"
  refineTypeName: "Refine",

  settings: {
    maxErrors: 8,                     // cap buffered diagnostics (DoS guard)
    useEval: true,                    // disable where unsafe-eval is blocked by CSP
    exactOptionalPropertyTypes: false,
    immutableTypes: false,
  },
}
```

* **`validationMessages`** is the place for i18n or project wording -
  it changes every message globally, unlike the per-field [custom error messages](/validation/error-handling#custom-error-messages) you set on a handler.
* **`refineTypeName`** renames `VRefine` if it collides with something in your codebase.
  The name is global and import-free either way. [Details ›](/validation/refine)
* **`settings.useEval: false`** is the option to reach for when a strict Content Security Policy forbids `unsafe-eval`;
  validation falls back to dynamic checking.
* **`settings.exactOptionalPropertyTypes: true`** aligns runtime check semantics with the TypeScript flag of the same name.

## What the scaffolder writes

Rather than assembling this by hand, let [kosmo folder](/cli/folder) write the right config for your answers - interactively, or from flags.
It names the bases after the folder: `/<folder>` for the frontend, `/<folder>/api` for the backend.

For reference, these are the configs it produces for a folder named `front`:

### What the scaffolder writes - React + Hono

```ts
// React + Hono
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  frontend: {
    stack: "react",
    base: "/front",
    fetch: true,
    ssr: false,
    ssg: false,
    tanstack: { query: false },
  },
  backend: {
    stack: "hono",
    base: "/front/api",
  },
  validation: true,
});
```

### What the scaffolder writes - Frontend only

```ts
// Frontend only
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  frontend: {
    stack: "react",
    base: "/front",
    fetch: true,
    ssr: false,
    ssg: false,
    tanstack: { query: false },
  },
});
```

### What the scaffolder writes - Backend only

```ts
// Backend only
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  backend: {
    stack: "koa",
    base: "/front/api",
  },
  validation: true,
});
```

### What the scaffolder writes - MDX docs

```ts
// MDX docs
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  frontend: {
    stack: "mdx",
    base: "/docs",
    fetch: true,
    ssr: true,
    ssg: true,
  },
});
```

### What the scaffolder writes (cont.)

> Changing what a folder has - adding `ssr`, a `backend`, `validation` - requires a
> **dev server restart**. The config is read once at startup.

## Bringing your own generator

Each block accepts a `generator` key that replaces the built-in one for that slot.
This is the escape hatch for a framework or a validator KosmoJS does not ship:

```ts
frontend: {
  stack: "react",
  base: "/",
  generator: myReactGenerator(),
  fetch: { generator: myFetchGenerator() },
  ssr: { generator: mySSRGenerator() },
},
backend: {
  stack: "hono",
  base: "/api",
  generator: myHonoGenerator(),
  openapi: { generator: myOpenapiGenerator() },
},
validation: { generator: myValidationGenerator() },
```

The order generators run in is fixed and does not depend on how you write the config:

```txt
core  ->  backend  ->  validation  ->  openapi  ->  fetch  ->  frontend  ->  ssr  ->  ssg
```

`coreGenerator` always runs first and is never listed.

## Project Settings - `package.json`

A few settings are project-wide rather than per-folder, and live in the root `package.json`:

```json [package.json]
{
  "type": "module",
  "distDir": "dist", // [!code hl:3]
  "devPort": 4556,
  "previewPort": 4558,
  "scripts": {
    "dev": "kosmo serve",
    "build": "kosmo build",
    "preview": "kosmo preview",
    "typecheck": "kosmo typecheck",
    "folder": "kosmo folder"
  }
}
```

| Field | Default | Meaning |
|---|---|---|
| `distDir` | `"dist"` | Build output directory for every folder |
| `devPort` | `4556` | Port the dev server listens on |
| `previewPort` | `4558` | Port [kosmo preview](/dev-build-run/production-preview) listens on |

> Changing `distDir` also means updating `.gitignore`, which the scaffolder points at the default `/dist/`.

Four scripts take optional folder names -
`pnpm dev front`, `pnpm build admin`, `pnpm preview front`, `pnpm typecheck admin front` -
and act on every source folder when given none.

`previewPort` is separate from `devPort` so preview and the dev server can run at the same time.

## TypeScript Config

### Root tsconfig.json

The project root has a `tsconfig.json` covering anything you keep outside `src/`.

It starts with only the ambient declarations in scope, so add the paths you want [typechecked](/cli/typecheck):

```json [tsconfig.json]
{
  "extends": "./lib/tsconfig.json",
  "include": ["./lib/*.d.ts"]
}
```

The root `include` is for code nothing imports - a migration script, a worker,
a standalone config, a helper you only ever run by hand.
Those have no importer to pull them in, so they are checked only if you list them here.

Shared code is the other way round. Anything a source folder imports is checked along with that folder,
so it does not need listing - adding it here only means it is checked on a root run too,
rather than only when its importer is.

When you add such a path, add to the list rather than replacing it.
This is **essential**: `include` replaces rather than merges with the config it extends,
so `./lib/*.d.ts` has to stay in it.

> Merging extended arrays has been [requested since 2017](https://github.com/microsoft/TypeScript/issues/20110)
> and is still open, so carrying the entries over by hand is the only option.

***

::: warning Never add `lib/` itself
`./lib/*.d.ts` matches only the ambient declarations at the top of `lib/` - that entry is meant to be there.
The rest is derived code, generated against each folder's own path mappings and already checked by that folder's run.
In the root program `_/` resolves against the wrong folder, so you get errors in files you cannot fix -
they are rewritten on the next run.
:::

### Per-folder tsconfig.json

Each source folder has its own `tsconfig.json` extending a derived base in lib dir:

```json [src/front/tsconfig.json]
{ "extends": "../../lib/front/tsconfig.json" }
```

The base `tsconfig.json` supplies the framework's `jsxImportSource`, the reserved path mappings,
and strict compiler settings. Anything you add in your own `compilerOptions` wins, and applies to that folder only:

```json [src/front/tsconfig.json]
{
  "extends": "../../lib/front/tsconfig.json",
  "compilerOptions": {
    "exactOptionalPropertyTypes": false
  }
}
```

Note there is no `include` in a source folder's `tsconfig.json`.
The base `tsconfig.json` already has everything a source folder normally needs.

But if you really need to include more, carry these base entries over first:

```json
["./", "../../lib/<folder>/", "../../lib/*.d.ts"]
```

So your file should look like this:

```json [src/front/tsconfig.json]
{
  "extends": "../../lib/front/tsconfig.json",
  "include": ["./", "../../lib/front/", "../../lib/*.d.ts", "../../shared"]
}
```

::: tip You do not need `include` to *use* shared code
Anything you import is typechecked along with the file importing it.
`import { formatUser } from "@/shared/user"` pulls `shared/user.ts` into that
folder's program whatever `include` says - the `@/` prefix resolves it,
and there is nothing to add to any `tsconfig.json`.
:::

---

---
url: /essentials/frameworks.md
description: >-
  What each backend and frontend framework supports in KosmoJS - mixed segments,
  power syntax, streaming SSR, SSG, TanStack Query, layouts, data loading and
  hooks - in one table.
---

Routing conventions, validation, middleware composition and the fetch clients are **identical across every framework**.

This page is about the places where they aren't -
gathered here so you can choose a stack without hunting through six pages of info boxes.

## Backends

| | Hono | H3 | Koa |
|---|:---:|:---:|:---:|
| Runtimes | Node · Deno · Bun · Workers · edge | Node · Deno · Bun · edge | Node (Deno/Bun via `node:http` compat) |
| Handler style | return `ctx.json()` / `ctx.text()` | return the value directly | mutate `ctx.body` |
| Raw params | `ctx.req.param()` | `event.context.params` | `ctx.params` |
| Validated params | `ctx.validated.params` | `ctx.validated.params` | `ctx.validated.params` |
| Route-specific types | Variables, Bindings | Context | State, Context |
| Global types (`api/env.d.ts`) | `DefaultVariables`, `DefaultBindings` | `DefaultContext` | `DefaultState`, `DefaultContext` |
| Error entry point | `app.onError()` | `app.use(onError(...))` | middleware around `await next()` |
| [Mixed segments](/routing/params#mixed-segments) | ⚠️ partial | ⚠️ partial | ✅ full |
| [Power syntax](/routing/params#power-syntax) | ⚠️ matches, params renamed `_0abc` | ❌ won't match | ✅ full |

**Choosing:** take Hono for maximum performance and the widest runtime reach;
H3 for the same, with a stronger Web-standards focus;
Koa for a mature Node ecosystem - and it is the only backend with complete mixed-segment and power-syntax support.

[Details ›](/backend/intro)

## Frontends

| | React | SolidJS | Vue | Svelte | MDX |
|---|:---:|:---:|:---:|:---:|:---:|
| Page extension | `.tsx` | `.tsx` | `.vue` | `.svelte` | `.mdx` / `.md` |
| Layout file | `layout.tsx` | `layout.tsx` | `layout.vue` | `layout.svelte` | `layout.mdx` |
| Renders children with | `<Outlet/>` | `props.children` | `<RouterView/>` | `{@render children()}` | `props.children` |
| `jsxImportSource` | `react` | `solid-js` | `vue` *(JSX only)* | n/a | `preact` |
| Data loading export | `loader` | `preload` | `loader` | `loader` | `loader` |
| Reading loaded data | `useLoaderData` *(react-router)* | `createAsync` | `useLoaderData` *(`_/use`)* | `useLoaderData` *(`_/use`)* | `useLoaderData` *(`_/use`)* |
| Needs `<Suspense>` | ❌ | ✅ | ❌ | ❌ | ❌ |
| [\_/use module](/frontend/hooks) | ❌ | ❌ | ⚠️ `useLoaderData` only | ✅ | ✅ |
| [Streaming SSR](/frontend/server-side-render#stream-rendering) | ✅ | ✅ | ✅ | ❌ | ❌ |
| [SSG](/frontend/static-site-generation) | ✅ | ✅ | ✅ | ✅ | ✅ |
| [TanStack Query](/frontend/tanstack-query) | ✅ | ✅ | ✅ | ✅ | ❌ |
| TanStack read hook | `useQuery(opts)` | `useQuery(() => opts)` | `useQuery(opts)` | `createQuery(() => opts)` | – |
| [Mixed segments](/routing/params#mixed-segments) | ⚠️ `.ext` suffix only | ❌ | ✅ | ✅ | ✅ |
| [Power syntax](/routing/params#power-syntax) | ❌ | ❌ | ❌ | ❌ | ❌ |

### Reading the exceptions

* **SolidJS is the only frontend that needs a `<Suspense>` boundary** in the common case.
  `createAsync` suspends; the other frameworks' loaders resolve before render.
  KosmoJS ships no boundary for you - scoping it is your call.
  [Why ›](/frontend/data-preload#suspense-is-your-responsibility)
* **Svelte and MDX render to strings only.** They implement `renderToString` but not `renderToStream`,
  and their folders don't accept the streaming [renderMode](/frontend/server-side-render#selecting-the-render-mode).
* **MDX has no client runtime**, so TanStack Query is unavailable there. Fetch with an MDX `loader` instead.
* **Svelte does not use SvelteKit.** KosmoJS uses only Svelte's UI layer,
  so data loading is the `loader` export, not SvelteKit's `load`, and there are no `+page` files.

## Routing Syntax Support

The parameter syntaxes are the same everywhere; only the exotic ones vary.

| Syntax | Example | Everywhere? |
|---|---|---|
| Required `[id]` | `users/[id]` | ✅ all backends and frontends |
| Optional `{id}` | `users/{id}` | ✅ all backends and frontends |
| Splat `{...path}` | `docs/{...path}` | ✅ all backends and frontends |
| Mixed segment | `files/[name].[ext]` | ⚠️ see tables above |
| Power syntax | `book{-:id}-info` | ⚠️ Koa only |

**Practical rule:** keep frontend routes to the three plain syntaxes.
Use mixed segments on the API side, where support is complete on Koa and workable on Hono/H3.
Reach for power syntax only on a Koa backend.

[Parameter details ›](/routing/params)

## Mixing Frameworks

Support differences are per **source folder**, not per project -
a folder runs exactly one frontend and at most one backend.
So the differences above are choices you make per app, not constraints you carry project-wide:

```txt
src/
├── marketing/    MDX + SSG        -> static, no backend
├── app/          React + Hono     -> SSR, streaming, TanStack Query
└── admin/        Vue + H3         -> CSR
```

A folder also ignores other frameworks' files: a Vue folder skips `.tsx`,
a React folder skips `.vue`/`.svelte`. [Details ›](/frontend/intro#extensions-per-framework)

---

---
url: /essentials/migration-tips.md
description: >-
  Translation guide for developers moving to KosmoJS from Next.js App Router,
  TanStack Start/Router or tRPC - server actions, route groups, parallel routes,
  loading.tsx, revalidateTag, next/image, validateSearch, routeTree.gen.ts and
  middleware.ts, each mapped to its KosmoJS equivalent or explicitly marked as
  having none.
---

If you are arriving from **Next.js App Router**, **TanStack Start/Router** or **tRPC**,
most of what you know transfers - and a few things deliberately don't.

The one shift worth internalizing first: **the client/server boundary is an HTTP call.**

Server code lives in `api/`, client code in `pages/`, and a typed fetch client carries the types across.
There is no interleaving of server and client code in one file.
During SSR that call runs [**in-process**](/fetch/isomorphic-clients), so the boundary costs nothing on the server.

The second shift: **the unit of an app is a [source folder](/essentials/project-structure).**

Not a route group or a workspace package. A folder has its own framework, base URL, middleware
and build - so several organizational features other frameworks provide inside one app are
structural here instead.

## Quick reference

| You're looking for | In KosmoJS |
|---|---|
| `app/page.tsx` | a folder with an [index file](/routing/rationale) - `pages/users/[id]/index.tsx` |
| `[id]` / TanStack `$id` | `[id]` - same concept, [required param](/routing/params) |
| `[...slug]` / `[[...slug]]` | `{...path}` - one splat [covers both](/routing/params) |
| optional segment | `{id}` - same concept, [optional param](/routing/params) |
| `layout.tsx` / `_layout` | `layout.*` in a [route folder](/frontend/layouts) |
| `not-found.tsx` | `pages/404.*` - a [dedicated](/frontend/error-pages) page for 404 errors |
| `loading.tsx` / `error.tsx` | your framework's Suspense / error boundary, at [app.\*](/frontend/application) |
| `(group)` route groups | a separate [source folder](/essentials/project-structure#inside-a-source-folder) |
| `@slot` parallel / `(.)` intercepting | no equivalent - compose in a layout / use modal state |
| `route.ts` route handlers | [defineRoute](/backend/intro#defining-endpoints) in `api/**/index.ts` |
| `middleware.ts` | global [api/use.ts](/backend/middleware) per app, or  [cascading use.ts](/backend/cascading-middleware) per subtree |
| `"use server"` / Server Actions | an API route + its [fetch client](/fetch/intro) |
| `createServerFn` | ditto |
| tRPC procedures | route name + HTTP method, [typed](/fetch/type-safety) / [validated](/validation/payload) end to end |
| Zod schemas | TypeScript types - [validators are derived](/validation/intro) |
| `validateSearch` | not implemented; validate [query](/validation/payload) on the API contract |
| `routeTree.gen.ts` | nothing to register - filesystem is the [route tree](/routing/intro) |
| `revalidatePath` / `revalidateTag` / ISR | no equivalent - cache at CDN/proxy, or SSG |
| `next/image`, `next/font` | no equivalent - bring your own |
| `next/link` | typed [Link](/frontend/link-navigation) component |
| `next/head` / `metadata` | MDX frontmatter, or the SSR entry's `head` |
| `next.config.js` | per-folder [kosmo.config.ts](/essentials/config) (it *is* the Vite config) |
| `next start` | [node dist/run.js -p 4556](/dev-build-run/building-for-production) |
| `.next/` | [dist/\<folder>/](/dev-build-run/building-for-production#build-output) |
| multi-zone | multiple [source folders](/essentials/project-structure#inside-a-source-folder) in one project |

## Routing

### `app/page.tsx` and why folders

A route is a **folder with an `index` file**: `pages/users/[id]/index.tsx` -> `/users/:id`.

Only `index` is the route; every sibling file is an obviously-colocated helper.
That is the whole reason for the extra folder - at scale, `schema.ts` next to `page.tsx` is ambiguous, and here it never is.
[Details ›](/routing/rationale)

### Params

Different sigils, same concepts - `[id]` required, `{id}` optional, `{...path}` splat.
[Details ›](/routing/params)

### `[[...slug]]` - optional catch-all

There is no separate required-vs-optional catch-all.

The splat `{...path}` matches **any number of segments including zero**,
so `docs/{...path}` matches `/docs` as well as `/docs/a/b/c` - covering both `[...slug]` and `[[...slug]]` with one form.
[Details ›](/routing/params#splat-parameters)

### `routeTree.gen.ts` - the central route tree

There is no route tree to register or import.

Routing is filesystem-driven; the route config is derived per source folder into `lib/` and handed to the framework's native router.
Treat it as a build artifact - you never edit or read it.
[Details ›](/frontend/routing#routes)

### `(group)` - route groups

There is no route-group syntax, and none is needed.

Next's `(group)` organizes routes without affecting the URL - a way to separate concerns inside one app.
KosmoJS separates concerns one level up: a [source folder](/essentials/project-structure) is an independent app
with its own framework, base URL, middleware and build.
The separation route groups gesture at is structural here rather than a naming convention.

### `@slot` parallel routes and `(.)` intercepting routes

**No equivalent.** One folder maps to one route.

* *Parallel routes* render several independent pages into named slots of one layout.
  Build it by rendering multiple components in a layout and fetching their data independently.

* *Intercepting routes* show a route differently depending on how you arrived (photo-in-a-modal vs. the full page).
  Build it with client-side modal state, or your router's modal patterns.

### `loading.tsx` / `error.tsx` / `not-found.tsx`

There are **no per-route special files** for loading and error states - they are handled with each
framework's own primitives rather than a KosmoJS file convention.
Global loading, Suspense and error boundaries belong at the [app.\*](/frontend/layouts#global-layout-via-app-file) level.

Not-found **does** have a built-in: a [pages/404.\*](/frontend/error-pages) component is rendered for unmatched routes.
Backend errors are separate and centralize in [api/errors.ts](/backend/error-handling).

::: tip Suspense is your responsibility
KosmoJS ships no `<Suspense>` boundary on purpose - one app-wide boundary collapses the whole page to a single fallback.
Scope it yourself.
[Details ›](/frontend/data-preload#suspense-is-your-responsibility)
:::

### Nested layouts, and do they persist state?

Same idea as `layout.tsx` / `_layout`: a `layout` file wraps its folder and subfolders, nesting by folders.
And yes - navigating between siblings under one layout swaps only the child,
so the layout stays mounted and **its state is preserved**, exactly as in App Router.
It remounts only when navigation leaves its subtree.
[Details ›](/frontend/layouts)

### `beforeLoad` and `validateSearch`

There is no proprietary `beforeLoad`-style hook - your framework's primitives are untouched,
so use React Router's `loader`, Solid Router's `preload`, or Vue Router's navigation guards directly.

Client-side typed/validated **search params are not implemented yet** - it's a considered feature.
Query params are validated on the *API contract* (the `query` target, with `VRefine` constraints, surfaced through the fetch clients),
but there is no client-side `validateSearch` typing `useSearch()` on the page route the way TanStack does.
For now, read search params with your framework's native router.
[Details ›](/validation/payload#validation-targets)

## Data fetching

### React Server Components and `"use server"`

**No RSC, and no `"use client"` / `"use server"` directive boundary - by design.**

Server code lives in `api/`, client code in `pages/`, and a plain HTTP API sits between them with typed fetch clients across the wire.
There is no interleaving of server and client code in one file and no new mental model to learn: the boundary is the network call.

And with the isomorphic client that boundary is free on the server - during SSR the call runs in-process, with no network layer at all.
[Details ›](/fetch/isomorphic-clients)

### Server functions / `createServerFn` / Server Actions

**There aren't any, and you don't need them.**

A server function exists to run server-only code from the client without hand-writing an endpoint -
which is exactly what an API route plus its typed client already gives you, with validation and OpenAPI included.

The same client is isomorphic: in-process during SSR, a same-origin request on the client.

Do mutations by defining a normal `POST`/`PUT`/`DELETE` route and calling its client.
Note there is no progressive-enhancement no-JS form submit as a first-class feature,
and no `useFormState`/`useActionState` equivalent - use your framework's form state plus the client's
[validationSchemas](/fetch/validation#validation-schemas) for field errors.

### Can a page read the database directly?

**Not the RSC way** - data flows through the API layer rather than direct DB access in a page.
During SSR this is not a network hop: the isomorphic client dispatches to the backend route `in-process` (no socket),
so you get the API boundary without the round-trip cost.
[Details ›](/fetch/isomorphic-clients)

### Loaders, and `loaderDeps` / staleness

Loaders work the way you expect: `export loader` on React, Vue, Svelte and MDX,
`export preload` on SolidJS - the loader simply being your fetch client's method exported under the name the router expects.

There is **no built-in loader cache** and no `loaderDeps`/staleness model.
React and Solid reuse the in-flight result for that navigation; Solid's `preload` results are reused by `createAsync`.
For real caching, enable [TanStack Query](/frontend/tanstack-query) - a first-class option.
[Details ›](/frontend/data-preload#page-integration)

### `revalidatePath` / `revalidateTag` / ISR

**No equivalent.** No fetch-cache extensions, no tag or path revalidation, no ISR, and no partial prerendering.
Cache at the CDN or proxy layer; use [SSG](/frontend/static-site-generation) for fully static output.
After a mutation, refetch or invalidate your own client cache.

### Does SSR data fetching need plumbing?

No - fetch clients are isomorphic, and each framework's own hydration carries the result to the client, so nothing re-fetches.
You do not wire `dehydrate`/`hydrate` for that.
(TanStack Query is an opt-in layer; serializing *its* cache across SSR is on you.)
[Details ›](/fetch/isomorphic-clients)

## Backend

### `route.ts` route handlers / `createAPIFileRoute`

`defineRoute` in `api/**/index.ts`, returning an array of method handlers -
same idea, plus validation and a fetch client for free.

You don't write `Response.json()`, and there is no`NextRequest`/`NextResponse`: it's the native Hono/H3/Koa context.
[Details ›](/backend/intro#defining-endpoints)

### `middleware.ts` - global edge middleware

Global middleware lives in [api/use.ts](/backend/middleware) file.
Whatever it default-exports runs for every route in that app, with no registration.

```ts [api/use.ts]
import { use } from "_/api";

export default [
  use(async (ctx, next) => {
    // runs for every route under this folder's `backend.base`
    return next();
  }),
];
```

There is no `middleware.ts`, and nothing is exported from a config file to enable it -
the default export of `api/use.ts` is the registration.

Below it, a [cascading `use.ts`](/backend/cascading-middleware) in any `api/` subfolder wraps everything beneath it,
carrying typed context via `UseT`, and [slots](/backend/middleware#slot-composition) let a route substitute a global default in place.

Three differences from Next's `middleware.ts` are worth knowing before you port anything:

* **It is not at the edge.** It runs in your API server, in the same process as the handlers -
  there is no separate edge runtime, and no Web-API-only subset to code against.
* **It is per route, not per request.** Global middleware is composed into each route's chain,
  so a request matching no route never reaches it. Rewrites, redirects for unknown URLs,
  or blanket header injection belong at the reverse proxy, or on the native app instance in [api/app.ts](/backend/intro#foundation-files).
* **It never sees page requests.** `api/use.ts` covers routes under the folder's `backend.base` only.
  Next's `middleware.ts` intercepts page navigations too; there is no client-route interception layer here.
  Gate the client side in the global `app.*` wrapper or a [layout](/frontend/layouts) instead -
  and remember that a client-side check is UX, not security: the API middleware is what actually enforces it.

### Edge / Cloudflare / Deno / Bun

With Hono and H3 the API runs on Node, Deno, Bun, Cloudflare Workers and edge platforms unchanged via `app.fetch`;
Koa runs through the `node:http` compat layer.
There is **no automatic serverless/edge packaging** like Next's -
you run the bundled server, or wire `app.fetch` into an edge runtime yourself.
[Details ›](/dev-build-run/building-for-production#running-the-api-server)

### Auth

There is no bundled auth and no NextAuth integration. Any Hono/H3/Koa middleware works unchanged -
verify a token in a `use.ts` and set `ctx.state.user` / `ctx.set("user")`.
[Details ›](/backend/cascading-middleware#common-use-cases)

## Validation & types

### "Does it use Zod?"

No - and you don't hand-write schemas at all.

TypeScript types are converted to JSON Schema and compiled to TypeBox validators automatically,
so one type definition drives compile-time types, runtime validation, the fetch client and the OpenAPI spec.

There is no schema to drift from your types.
[Details ›](/validation/intro)

The trade-off worth knowing: you give up schema-level *transforms* and custom refinement functions,
and you get constraints declaratively through [VRefine](/validation/refine) instead.
Do transformation in the handler, where it's plain code.

### tRPC-style end-to-end type safety

Effectively yes, through typed fetch clients - params, payload and response types all derive from the same route definition,
with client-side validation before the request.
The difference is that it's **route-based** (path key + HTTP method) rather than procedure-based,
and it comes with automatic [runtime validators](/validation/intro) and [OpenAPI spec](/openapi),
which tRPC does not produce natively.
[Details ›](/fetch/intro)

### Compile-time or runtime?

Both, from one definition - which is the main difference from TanStack Router's compile-time-only route typing.
The derived validators run on real requests.
[Details ›](/essentials/why-codegen)

## Rendering

The dev server always renders on the client - Vite with HMR, for the fastest feedback loop available.
That is the **development** mode, not a rendering philosophy: it says nothing about what a folder ships.

In production, each folder picks its own mode:

* **CSR** - a static client bundle served alongside the API.
* **[SSR](/frontend/server-side-render)** - opt in per folder, then string- or stream-rendered per route.
* **[SSG](/frontend/static-site-generation)** - pre-rendered HTML at build time, available on every frontend. The closest thing to `output: export`.

Because dev never server-renders, the [preview command](/dev-build-run/production-preview) is the step before you ship:
it builds and serves the real production output - server-rendered pages, hashed assets, the production validation policy -
on its own port, so it can sit next to the dev server.

Migrators trip on this more than anything else, so make preview part of the loop rather than a last resort.

There is **no ISR, no on-demand revalidation and no partial prerendering**,
and islands / partial hydration is not offered as a named feature.

For `<head>`: MDX frontmatter drives it, or the SSR entry's returned `head`.
There is no `metadata` / `generateMetadata` export convention.

## Project & tooling

### `next.config.js`

Per-folder [kosmo.config.ts](/essentials/config). Vite's `UserConfig` goes in `viteConfig`
on the `frontend` and `backend` blocks - `plugins`, `resolve`, `css` and the rest.
There is no separate `vite.config.ts` and no project-wide kosmo config.

### `.next/` and `next start`

Build output is `dist/<folder>/` with `api/`, `client/`, `ssr/` and `ssg/` subdirectories, plus a `dist/run.js` dispatcher.
The `next start` equivalent is `node dist/run.js -p 4556` - one process serving every source folder.
It's `node:http`, so `bun` and `deno run -A` work too.
[Details ›](/dev-build-run/building-for-production)

### `next/image` and `next/font`

**No equivalent** - there is no image optimization or font pipeline. Bring your own.

### `next/link`

The typed [Link](/frontend/link-navigation) component whose `to` prop is a `[routeName, ...params]` tuple,
so renaming a route directory turns every stale link into a compile error.

### Multi-zone

The source-folder model *is* the multi-app story: per-folder base URLs, frameworks and builds inside one project, sharing types and a database layer directly.
Where Next stitches separate deployments together with multi-zone, KosmoJS keeps the apps in one codebase with no zone configuration.

### Deployment lock-in

None. It's a standard Node/Vite app - deploy the bundled servers to Node, Bun, Deno or the edge yourself.
You can deploy to Vercel as a Node app, but there are no Vercel-specific features and no dependence on them.

## What you gain

Worth naming, since it's the other half of the trade: derived **runtime validators** from your TypeScript types,
**typed fetch clients** with client-side validation, automatic **OpenAPI 3.1**,
and **multi-app orchestration** in one project - several frameworks side by side,
sharing types with no workspace protocols, each building and deploying independently.

[What KosmoJS is ›](/about) · [Feature overview ›](/features)

---

---
url: /essentials/why-http.md
description: >-
  The industry spent two decades pulling server logic out of the page, and is
  now putting it back? A look at what actually moved, and why KosmoJS keeps an
  explicit HTTP boundary while making it cost nothing during SSR - one
  isomorphic fetch client, two transports, validation on both ends.
---

A fair question, asked more than often:

> The whole industry is moving server logic back **into the page** - server components, `"use server"`, server functions.
> Why does KosmoJS still make me define an API route and call it over HTTP?

It is a good question, and it deserves more than "because REST". The honest answer starts with a bit of déjà-vu.

## We have been here before

Anyone who was writing web software in the early 2000s remembers what a page looked like:

```php
<?php
  $rows = mysql_query("SELECT * FROM users WHERE id = " . $_GET['id']);
  $user = mysql_fetch_assoc($rows);
?>
<h1><?= $user['name'] ?></h1>
<style>h1 { color: rebeccapurple }</style>
```

One file. Server logic, database access, markup and styles, colocated by default because there was nowhere else to put them.
It was **fast to write** - that part was never in dispute - and every interaction cost a full page reload.

Then the page learned to talk back without reloading. `XMLHttpRequest` arrived quietly -
shipped by a browser vendor for its own webmail product, which wanted to update part of a page instead of all of it -
and stayed a curiosity for years, worked around with hidden iframes by the few who cared.

What ended the obscurity was the free webmail service that opened, invite-only, in 2004.
A mailbox in a browser that behaved like a desktop application:
threads expanding, messages sending, labels applied, none of it costing a full-page reload.

It was the first time a mainstream audience used the technique daily without knowing it existed.
A mapping app that dragged instead of paginating followed a year later,
and in 2005 the whole approach finally got the name everybody used for the rest of the decade: `AJAX`.

What followed was twenty years of the same move, repeated:

| Step | What moved out of the page |
|---|---|
| XHR, then JSON over XML | The *rendering* of updates - server started answering with data |
| REST, then SPAs | The *routing and state* - the page became an application |
| A second client (mobile, then partners) | The *contract* - the API outlived the UI that prompted it |
| OpenAPI, GraphQL, typed clients | The *types* - the boundary became something you could check |

By the mid-2010s the shape had settled into something almost nobody had to argue for:
a rich client, a slim API, and a well-understood protocol between them.

Not because it was elegant, but because it survived contact with second clients,
third-party integrations, mobile teams, rate limits, caching layers, incident postmortems and audits.

And now the pendulum swings back: a component reads the database,
a function marked `"use server"` is called as if it were local,
and the file looks - squint a little - like that PHP page again.

## So what actually changed?

Here is where innocent questions are more useful than opinions.

The obvious reading is "we undid twenty years of work".
That reading is wrong, and worth dismissing carefully: **the boundary did not go away**.

A `"use server"` function still becomes an endpoint.
The compiler writes it, gives it a generated id, serializes arguments and results across the same network the PHP page did not have.
The client/server split is fully intact - it moved from something you *write* to something the framework *emits*.

That is a real **ergonomic win**, and it solves a real annoyance:
hand-writing an endpoint, a client, and the types on both sides, three times, for one button.

So the question isn't "server or page". It is narrower and more interesting:

> When the boundary becomes invisible, what else becomes invisible with it?

A few things that used to be obvious:

* **What is the URL?** Generated ids are not addresses you can share, curl, or put in a runbook.
* **Who else can call it?** A mobile app, a partner integration, a cron job, a support script -
  none of them import your React components.
* **What runs at the boundary?** Auth, rate limiting, request logging, tracing, validation -
  the things that live in middleware because they must apply to *everything* crossing the line.
* **What does the wire look like?** Payload shapes you can inspect in a proxy, in a log, in a HAR file from a user's browser.
* **What can be deployed separately?** A public API in a DMZ and an admin UI behind a VPN are one process,
  or two, depending on whether there is a boundary to cut along.

None of that is an argument that colocation is wrong.
It is an argument that the *explicitness* of the boundary was doing work that people mostly noticed when it was gone.

Which leads to the question this framework is an answer to:

> Colocation is nice because the boundary is cheap to cross.
> Explicitness is nice because the boundary is real. Do you actually have to pick one?

## KosmoJS's answer: keep the boundary, delete the latency

Server code lives in `api/`, client code in `pages/`, and an HTTP API sits between them.
Every endpoint has a URL. You can curl it, log it, proxy it, hand it to a mobile team,
put it in an [OpenAPI spec](/openapi), and deploy it on its own.

The part that makes this cheap is the [isomorphic fetch client](/fetch/intro) derived from each route -
meaning the same call site works in the browser and on the server, and only the transport underneath differs:

```ts
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

const user = await GET([123]); // identical code in a component and in a loader
```

| Where it runs | Transport | Cost of the boundary |
|---|---|---|
| Browser, after hydration | Global `fetch`, same-origin request | A normal HTTP request - as it should be |
| Server, during SSR | Direct dispatch into the API app | A function call and an object. **No socket, no localhost hop, no round trip.** |

During SSR the API is bundled *into* the SSR server, and the fetch client hands a real `Request` straight to the backend app instance.
What runs is not a shortcut around your API: it is your API, complete with routing,
[middleware](/backend/middleware), validation, error handling and response shaping.

Details worth knowing about that in-process path:

* **Headers from the incoming page request are forwarded as defaults**, so cookies and auth headers
  reach the route exactly as they would over the network. Anything you set on the call itself wins.
* **Redirects are followed in-process**, including the `303`/`301`/`302` rewrite to `GET`,
  up to the same five hops the fetch spec allows.
* **Native `fetch` is not patched.** Only the fetch clients switch transports;
  every other fetch in your app behaves exactly as it always did.
* **Nothing about the call site changes.** A loader is a loader; the framework's own data model -
  Solid's `createAsync`, React Router's `loader`, `useLoaderData` in Vue, Svelte and MDX - is what you write.
  [Details ›](/fetch/isomorphic-clients)

So the trade the industry seems to be posing - *keep the architecture and pay a round trip, or drop the architecture and get the speed* -
turns out not to be the only option on the table.
The round trip was never the point of the boundary; it was just the usual way of crossing it.

::: tip Where the fetch fires still matters
In-process dispatch applies to requests made **during rendering** - loaders, preloads, `createAsync`.
A fetch in `useEffect` / `onMounted` runs after hydration, in the browser, over the network -
because that is where and when it naturally happens.
:::

## Declared once, enforced on both ends

The other thing an explicit boundary buys is a place to state what may cross it.

Validation is declared in the route, as ordinary TypeScript types, next to the handler that relies on it.
From that single declaration KosmoJS compiles schemas that run in **both** directions:

```ts
export default defineRoute<"users/[id]", [
  number, // validate id param as number [!code hl]
]>(({ PUT }) => [
  PUT<{
    json: { // [!code hl:4]
      name: string;
      email: VRefine<string, { format: "email" }>
    },
  }>(
    async (ctx) => { /* ... */ },
  ),
]);
```

* **In the browser**, fetch client validates params and payload *before* the request leaves.
  Invalid data throws immediately - no round trip, and the same schemas are exposed
  as [validationSchemas](/fetch/validation#validation-schemas) for live form feedback.
* **On the server**, the request is validated again on arrival -
  because a server that trusts its clients is not a server, it is a suggestion box.

The two are the same compiled schema, so they cannot disagree, and neither can drift from the types the handler is written against.
[Details ›](/validation/intro#end-to-end-validation)

And under SSR, the client-side check is disabled automatically - validation runs on the API endpoint only.

## What this costs you

An honest list, because the trade is real:

* **You write a route file.** Not a function in a component - a file under `api/`, with a URL.
* **No closure capture across the boundary.** A page cannot reach into a server-side variable simply
  because it is in scope; it calls a route, and the route reads the database.
  This is the constraint that makes the boundary real.
* **No progressive-enhancement form posts**, no `useActionState` equivalent -
  form state is your framework's job, with the client's validation schemas for field errors.

And what it buys: an API a second client can use, a boundary your middleware actually controls,
URLs in your logs, a spec you can publish, folders you can deploy separately -
and, during SSR, none of the latency that usually comes with any of it.

## The déjà-vu, resolved

The 2000s page was fast to write and impossible to keep. The 2010s API was durable and chatty to build against.

They were solving different problems, and neither one was actually wrong about its own:

* colocation is about the cost of crossing a boundary
* separation is about whether the boundary exists

Those are independent questions, and answering them independently is the whole of the design here.
Keep the API. Make crossing it free where it can be free. Ask again in ten years.

***

* [Migration Tips](/essentials/migration-tips)
* [Isomorphic fetch](/fetch/isomorphic-clients)
* [Validation](/validation/intro)

---

---
url: /essentials/why-codegen.md
description: >-
  Two very different things share the word "codegen". KosmoJS only does the safe
  kind - derivation into a git-ignored lib/ folder, plus boilerplate seeded into
  blank files and never touched again.
---

For many of us, "codegen" is a good reason to close the tab. Most code generation earned that.
But two very different things share that one word.

## First, What Is What

**Consider a tool that writes a file, lets you edit it, then overwrites your edit.**

A perfect example of a "codegen" imperfection - the dark side.

Rails scaffolds, SOAP/WSDL stubs, Interface Builder, checked-in protoc output, Swagger client generators -
the story is always the same: you edited the output, something regenerated it, your work vanished.
So you stopped regenerating, and maintained a second source of truth by hand forever.

Call that **scaffolding** - written once, becomes yours, drifts.

**Now consider another tool. It reads your code and derives things you never edit.**

A perfect example of a compiler at work - the light side.

* `tsc` turns your TypeScript into JavaScript
* The JSX transform turns `<div/>` into function calls
* Vite turns your modules into a bundle
* Prisma turns a schema into a typed client

Nobody calls these a smell, and nobody edits their output.

Call that **derivation** - recomputed from a single input, never edited, disposable.

## What KosmoJS Does

### It derives

Your routes are the input.
Routing trees, typed fetch clients, validation schemas, the OpenAPI spec - all output, all landing in `lib/`, which is git-ignored.
Not a second copy of your code; a derivative of it.

Vite and friends do the same thing and hide the result in `node_modules`.
KosmoJS keeps it in `lib/` deliberately: when something looks wrong,
the derived code is right there in your editor, readable, with your own route names on it.

### It seeds

A newly created route file gets its boilerplate, so you are not bootstrapping every route by hand.

> Only blank files are seeded.
> The moment a file has content - boilerplate or your own edit - it is never touched again.
> Not by a re-seed, not by a template change, not by a version bump.

And if the boilerplate isn't what you want, adapt it or switch it off entirely - see
[backend](/backend/custom-templates) and [frontend](/frontend/custom-templates) templates.

### That's All

It doesn't scaffold in user space. It reads your routes, wires them into the native routers,
and derives assets you can import where you find them useful.

KosmoJS owns the `lib/` folder, you own `src/` and everything else.

***

The objection to codegen is really an objection to scaffolding.
Derivation is just compilation, and you already trust several layers of it.

Every project has derived artifacts. The only question is whether a machine derives them on every build,
or a person derives them by hand on a schedule they will eventually forget.

---

---
url: /cli/intro.md
description: >-
  Every KosmoJS command - create kosmo and kosmo folder for scaffolding, serve,
  preview, build and typecheck for everything after, plus the interactive and
  flag-driven modes and every message a command exits with.
---

KosmoJS ships two binaries.

**create-kosmo** bootstraps a project - you run it once, through `npm create kosmo`.

**kosmo** does everything after that. It comes with `@kosmojs/cli`, a devDependency of every project,
and `package.json` wires it to scripts so you rarely type the binary name:

| Script | Command | What it does |
|---|---|---|
| `pnpm dev` | `kosmo serve` | Dev server for every source folder |
| `pnpm preview` | `kosmo preview` | Production build, served and rebuilt on change |
| `pnpm build` | `kosmo build` | Production build |
| `pnpm typecheck` | `kosmo typecheck` | `tsc --noEmit` per source folder, plus the project root |
| `pnpm folder` | `kosmo folder` | Add a source folder to the project |

All five run from the **project root** - the directory holding `package.json`.

They read `distDir`, `devPort` and `previewPort` from it, and refuse to start if any is missing.

`-h` / `--help` prints the full usage for either binary.

## The commands

| Scaffolding | |
|---|---|
| [create kosmo](/cli/create) | Bootstrap a new project - run once |
| [kosmo folder](/cli/folder) | Add a source folder to an existing project |

| Running a project | |
|---|---|
| [kosmo serve](/cli/serve) | Dev server on `devPort`, Vite + HMR, always client-rendered |
| [kosmo preview](/cli/preview) | Production build served on `previewPort`, rebuilt on change |
| [kosmo build](/cli/build) | Production build only - `dist/run.js` plus a per-folder tree |
| [kosmo typecheck](/cli/typecheck) | `tsc --noEmit` per source folder, plus the project root |

## Interactive vs CLI mode

The two scaffolding commands - `npm create kosmo` and `kosmo folder` -
each have an interactive flow and a flag-driven one.

| Invocation | Mode |
|---|---|
| Any flag passed | CLI |
| No flags, stdout is a terminal | Interactive |
| No flags, stdout is **not** a terminal | CLI, with an empty flag set |

There is no partial prompting. Once you are in CLI mode, anything you left out
must have a default, or the command errors out.

`-q` / `--quiet` suppresses CLI mode's output. Errors still print.

### The non-terminal case

This is the one that surprises people, and it has nothing to do with how you
typed the command. The prompts disappear whenever stdout is not a terminal:

* piping the output - `pnpm folder admin | tee setup.log`
* running it from a setup or CI script
* running it in a container or an agent sandbox with no terminal attached

So the same invocation that prompts in your shell becomes a CLI-mode run with
no flags. It fails on the first required value rather than hanging on a question
nobody can answer.

That is deliberate: a scaffolder blocked on an invisible prompt is worse than
one that tells you which flag is missing.

## When a command refuses to run

| Message | Cause |
|---|---|
| package.json does not exist or some of distDir / devPort / previewPort is not set | Not in the project root, or some of listed key(s) are missing. |
| Invalid command, use one of folder, serve, build, preview, typecheck | Typo, or a command from another framework's CLI. |
| No source folders detected | No `src/*/kosmo.config.ts` anywhere. |
| Some of the given names do not contain a valid KosmoJS source folder | A named folder doesn't exist or has no config. |
| No folder name provided | `kosmo folder` in CLI mode with no name positional - including the non-TTY case. |
| frontend is required: either provide `--frontend <name>` or `--no-frontend` flag | Neither half of the pair was passed. |
| `--frontend` and `--no-frontend` are mutually exclusive; use only one | Both halves were. |
| Target dir is not empty. Either remove dir contents or provide `--overwrite` flag | `create kosmo` in CLI mode, non-empty target. |
| `./src/<name>` already exists. Either remove it or provide `--overwrite` flag. | `kosmo folder` in CLI mode, folder taken. |

---

---
url: /cli/create.md
description: >-
  Bootstrapping a KosmoJS project with npm create kosmo - the interactive flow,
  the flags, and what the new project contains.
---

### When a command refuses to run - npm

```sh
npm create kosmo demo
```

### When a command refuses to run - pnpm

```sh
pnpm create kosmo demo
```

### When a command refuses to run - yarn

```sh
yarn create kosmo demo
```

### When a command refuses to run (cont.)

The positional argument is the target directory, created if missing. Use `.` to bootstrap in the
current directory:

```sh
npm create kosmo .
```

A project name may contain alphanumerics and any of `. - + $ @`,
may not start with a dash, and may not contain path traversal.

## The interactive flow

If the target directory has anything in it other than `.git*`, `README*` or `LICENSE*`,
you are asked first what to do with it - remove the existing files, keep them and overwrite as needed, or cancel.

Then a handful of questions, all about the **first source folder**:

1. **Framework** - React, Vue, Solid, Svelte, MDX, or *None (API-only folder)*
2. **Backend Framework** - Hono, H3, Koa, or *None (client-only folder)*
3. **Enable server-side rendering (SSR)?** - skipped for MDX, where SSR is always on
4. **Enable static site generation (SSG)?** - asked only if SSR is enabled
5. **Enable TanStack Query?** - skipped for MDX, which does not support it

You are not asked for the folder's name or base: the first folder is always **`app`**, with its pages at `/` and its API at `/api`.
Add differently-shaped folders at any time with [kosmo folder](/cli/folder).

## CLI mode

```sh
# npm needs -- to pass flags through
npm create kosmo demo -- --frontend react --backend hono

# pnpm and yarn do not
pnpm create kosmo demo --frontend react --backend hono --ssr
```

| Flag | Meaning |
|---|---|
| `--frontend <name>` | `react`, `solid`, `vue`, `svelte`, `mdx`. |
| `--no-frontend` | API-only folder - no `pages/`, no client entries. |
| `--backend <name>` | `hono`, `h3`, `koa`. |
| `--no-backend` | Client-only folder - no `api/` directory. |
| `--ssr` | Enable [server-side rendering](/frontend/server-side-render). |
| `--ssg` | Enable [static site generation](/frontend/static-site-generation). Implies SSR. |
| `--tsq` | Enable [TanStack Query](/frontend/tanstack-query). Ignored on MDX folders. |
| `--overwrite` | Proceed even though the target directory is not empty. |
| `-q, --quiet` | Suppress output. |
| `-h, --help` | Print usage and exit. |

::: warning The frontend and backend choices are never implied
Either `--frontend <name>` **or** `--no-frontend` is required -
omitting both is an error, and passing them both is an error too (same for backend).
:::

## What you get

```txt
demo/
├── package.json               # type, distDir, devPort, previewPort, scripts, deps
├── .gitignore
└── src/app/
    ├── kosmo.config.ts        # the frontend / backend blocks your answers imply
    ├── public/favicon.svg
    ├── api/index/index.ts     # empty stub, if a backend was chosen
    ├── pages/index/index.tsx  # empty stub, extension per framework
    └── entry/client.ts        # empty stub, if a frontend was chosen
```

The stubs are **empty on purpose**. They are filled on the first `pnpm dev` or `pnpm build`,
along with everything else the folder needs.

`package.json` carries three project-level settings alongside the usual fields -
[distDir, devPort, previewPort](/essentials/config#project-settings-package-json) -
and the dependencies each chosen generator declares.

***

### After bootstrap

`cd` into freshly created project (unless the project was bootstrapped in the current folder):

```sh
cd ./demo
```

### Install Dependencies

#### Install Dependencies - npm

```sh
npm install
```

#### Install Dependencies - pnpm

```sh
pnpm install
```

#### Install Dependencies - yarn

```sh
yarn install
```

### Start the dev server

The dev server completes the setup: it seeds the remaining project files and wires everything together.
From then on it watches your routes and recomputes as you work:

#### Start the dev server - npm

```sh
npm run dev
```

#### Start the dev server - pnpm

```sh
pnpm dev
```

#### Start the dev server - yarn

```sh
yarn dev
```

#### Start the dev server (cont.)

Your app is now running at `http://localhost:4556`.

---

---
url: /cli/folder.md
description: >-
  Adding a source folder to an existing project, interactively or from flags,
  and installing the dependencies a new folder needs.
---

A project is a set of [source folders](/essentials/project-structure), and you can add one at any time.

Each is a self-contained app with its own stack and its own URL prefixes -
e.g. a marketing site at `/`, an admin app at `/admin`, an API-only service at `/svc`, etc.

```sh
npm run folder <name>   # interactive
# or `pnpm folder <name>`
```

**Folder Name** - becomes `src/<name>`, and gives the folder its prefixes:

* pages at `/<name>`
* API at `/<name>/api`.

Edit `base` in `kosmo.config.ts` afterwards if you want different prefixes.

If `src/<name>` already exists, you are offered to remove / overwrite before proceed, or cancel.

Interactive prompts you'll answer to:

* **Frontend** and **Backend**, each with a *None* option
* **SSR**, then **SSG** if SSR is on, then **TanStack Query**

## CLI mode

The same flags as `create kosmo`, providing folder name as first argument.

```sh
pnpm folder admin --frontend solid --backend h3
pnpm folder svc   --no-frontend    --backend hono
pnpm folder docs  --frontend mdx   --no-backend --ssg
```

> Folder name is required, omit it and you get an error: `No folder name provided`.

That gives `admin` its pages at `/admin` and its API at `/admin/api`,
`svc` an API at `/svc/api` and no pages, `docs` pages at `/docs` and no API.

Without `--overwrite`, an existing `src/<name>` is an error rather than a prompt:

```txt
./src/admin already exists. Either remove it or provide --overwrite flag.
```

## Install new dependencies

A new folder usually brings new dependencies.
The command diffs `package.json` before and after and prints only what was added:

```txt
💡 New dependencies added:
solid-js, h3

📦 Install them before continue:
$ npm install
```

Run the install before starting the dev server.

The new folder's `kosmo.config.ts` already declares the stack,
but the packages it writes imports for are not on disk yet.

A dev server that was already running does not pick the folder up: folders are collected once, at startup.
Restart it.

::: tip Changing the folder later
`kosmo folder` writes `kosmo.config.ts` once; editing it afterwards is expected and supported.
The config is read at startup, so restart the dev server after turning `ssr` on, adding a `backend`, or changing a `base`.
[Configuration ›](/essentials/config#the-shape)
:::

---

---
url: /cli/serve.md
description: >-
  The development server - one process for the whole project, client modules
  through Vite with HMR, API routes hot-reloaded in the same process, on
  devPort.
---

`serve` is the command you leave running while you work.

One process covers every selected folder, and both halves of each:

* client modules go through Vite, with HMR
* API routes run in the same process, hot-reloaded on change
* requests are dispatched between the two by the folder's `backend.base`

No second command to start, no proxy to configure.

```sh
pnpm dev               # every folder
pnpm dev admin front   # just these two
```

Listens on **`devPort`** (default `4556`, configured in `package.json`).

## Dev is always client-rendered

`serve` is Vite + HMR + client-side rendering, whether or not the folder has [SSR enabled](/frontend/server-side-render).

Server rendering happens in the production build, so there is no server-rendered markup to look at here.

This catches people out coming from Next, Nuxt or TanStack Start, where dev
mirrors production rendering. To see anything server-rendered, use [kosmo preview](/cli/preview).

## Selecting folders

With no arguments, every source folder is served.
Name one or more to narrow the scope - the names are directory names under `src/`.

A name with no `src/<name>/kosmo.config.ts` stops the command before anything runs,
and a project with no folders at all reports `No source folders detected`.

Narrowing changes what the one process serves: folders you left out are not mounted,
so their paths 404 on `devPort` rather than falling through.

## Ports

`devPort` is the only port you address.

Each folder's Vite server and HMR socket get their own, picked from a free range derived from `devPort` -
which is why the command insists on a `devPort` below `64000`, so that range still fits.

`devPort` is not negotiated.

If something else holds it, the dev server reports `Failed to start dev server on port 4556` and exits rather than moving,
so the URL you have open never silently changes under you.

[Development workflow ›](/dev-build-run/development-workflow)

---

---
url: /cli/preview.md
description: >-
  Building and serving the production output on previewPort, rebuilt on change -
  the only way to see SSR, bundling and the production validation policy
  locally.
---

`preview` is the dev loop run against production output.

The dev server never builds: it serves modules through Vite, client-rendered, with HMR.

That makes it fast, and it also means a whole class of things simply does not exist there -
server-rendered markup, hashed assets, chunk splitting, tree-shaking, the production validation policy.

None of them are visible until you build, which is the gap `preview` closes.

It builds the selected folders, runs [dist/run.js](/dev-build-run/building-for-production#one-entry-point-for-the-whole-project) -
the same entry point production starts - then watches your sources and rebuilds on change, restarting the runner.

```sh
pnpm preview         # every folder
pnpm preview front   # just this one
```

Listens on **`previewPort`** (default `4558`, configured in `package.json`).
That is deliberately not `devPort`: preview and the dev server run side by side,
so you can compare client-rendered and server-rendered output in adjacent tabs.

## Selecting folders

With no arguments, every source folder is built and served.
Name one or more to narrow the scope - the names are directory names under `src/`.

A name with no `src/<name>/kosmo.config.ts` stops the command before anything runs,
and a project with no folders at all reports `No source folders detected`.

Folders you leave out keep whatever is already in `distDir`, so the runner still serves them -
built earlier, and not rebuilt when their sources change.

## Rebuild, not HMR

A change triggers a full production rebuild, so expect seconds rather than the milliseconds of HMR.
There is no module patching and no preserved state, because a production bundle has no running module graph to patch -
and a preview you cannot trust is worse than none.

A failed rebuild leaves the previous build serving,
so a typo mid-edit prints an error to the terminal without taking the page down.

Iterate on the dev server; reach for `preview` to verify.

[Production preview ›](/dev-build-run/production-preview)

---

---
url: /cli/build.md
description: >-
  The production build - what it emits per folder, how partial builds stay safe,
  and the manifest dist/run.js reads at startup.
---

```sh
pnpm build         # every folder
pnpm build front   # just this one
```

The same build `preview` runs, minus the server and the watcher.
Output goes to the `distDir` set in `package.json` - `dist/` by default.

With no arguments, every source folder is built. Name one or more to narrow the scope -
the names are directory names under `src/`.

A name with no `src/<name>/kosmo.config.ts` stops the command before anything is written,
and a project with no folders at all reports `No source folders detected`.

## What one folder's build does

Each selected folder is built in full, in order:

1. **Resolve routes.** Every route file is read and its types resolved -
   this is what produces the validation schemas and the fetch client signatures.
2. **Run each generator's build step**, in the [fixed order](/essentials/config#bringing-your-own-generator).
3. **Bundle the client**, if the folder has a `frontend` - into `dist/<folder>/client`,
   with `base` set to the folder's `frontend.base` and a Vite manifest alongside it.
4. **Bundle the backend**, if the folder has a `backend` - into `dist/<folder>/api`, as ESM with sourcemaps.
   Two entry points: `api/app.ts` and `api/server.ts`.
5. **Run each generator's post-build step.** This is where the SSR/SSG bundles produced, if either enabled.

Then the folder's manifest is written, and once every folder is done, `dist/run.js` is deployed.

[Details ›](/dev-build-run/building-for-production#build-output)

## Partial builds

Building a subset leaves the other folders' output untouched, so `pnpm build app` never invalidates `admin`.

Within a folder, though, the build is not incremental:
the client and backend output directories are emptied before they are rewritten.
A folder is always rebuilt whole, never patched.

## The folder manifest

Each build writes `dist/<folder>/kosmo.json`, describing the folder in the terms `dist/run.js` needs to route to it:

```json [dist/front/kosmo.json]
{
  "name": "app",
  "frontend": { "base": "/" },
  "backend": { "base": "/api", "aliasPatterns": [] },
  "ssr": false
}
```

`frontend` and `backend` are present only when the folder has that half.

`dist/run.js` reads these at startup to discover which folders exist and what each one claims.
That indirection is what makes partial builds safe:
the runner holds no folder-specific data, so it is rewritten identically on every build,
and a folder built an hour ago is still served by a runner started after a one-folder rebuild.

[Details ›](/dev-build-run/building-for-production#one-entry-point-for-the-whole-project)

## Notes

The Vite cache is keyed by command - `var/.vite/<folder>/build/` -
so building never invalidates the dev server's cache,
and `preview` shares the build's cache rather than warming a third one.

The build does not typecheck. `tsc` is a separate step - [kosmo typecheck](/cli/typecheck) -
so a type error does not stop a bundle from being emitted.

What you deploy depends on how each folder renders.
[Details ›](/dev-build-run/building-for-production#what-to-deploy)

---

---
url: /cli/typecheck.md
description: >-
  Typechecking each source folder against its own tsconfig, plus the project
  root run and what its include list decides.
---

`typecheck` is the type safety the rest of KosmoJS leans on, run on demand.

```sh
pnpm typecheck          # every folder, plus the project root
pnpm typecheck admin    # just this folder
pnpm typecheck .        # project root only
pnpm typecheck . admin  # project root and admin
```

Typecheck is a manual run. The dev server and the build do not typecheck before transpiling.

So a stale `defineRoute<"users/[id]">`, left behind after renaming `api/users/`,
is a compile error neither of them will mention - the bundle is emitted and the route 404s.

This is the command that catches it, in CI or before you commit.

:::details If you need it running automatically before `pnpm build`

Add a `prebuild` script in `package.json`:

```json [package.json]
{
  "scripts": {
    "prebuild": "pnpm typecheck"
  }
}
```

:::

## Under the hood

It runs `tsc --project <tsconfig> --noEmit` in sequence,
using the `typescript` version installed in the project: one run per selected source folder,
plus one for the project root.

Every selected tsconfig is checked, even after one of them fails. A failing
folder does not hide the state of the others, so one run tells you everything
there is to fix rather than the first thing.

The command exits `1` if any run reported errors, and `0` only when all of them
passed - so `pnpm typecheck` works as a CI gate without any extra wiring.

### Why separate runs

Each source folder has its own [tsconfig.json](/essentials/config#typescript-config) with its own path mappings.
A single `tsc` over the whole project would resolve them against the wrong one, so the folders are checked one at a time instead.

## Selective typechecking

Provide no arguments and every source folder is checked, along with the project root.

```sh
# every folder, plus the root
pnpm typecheck
```

Provide one or more names and only those are checked, project root ignored.

```sh
# one folder, no root
pnpm typecheck admin
```

> The command fails loudly if a name is not a folder in `src/` with a valid `kosmo.config.ts`.

Provide `.` and only project root is checked, no source folders.

```sh
# the root, no folders
pnpm typecheck .
```

Provide `.` with folder name(s) and you get the root checked along with the provided names.

```sh
# the root and admin folder
pnpm typecheck . admin
```

---

---
url: /routing/intro.md
description: >-
  KosmoJS uses directory-based routing to map file system structure directly to
  URL paths. Folder names become path segments with index files defining
  endpoints and components.
---

With directory-based routing, folder names become URL path segments, and `index` files define the actual endpoints or components.
No separate routing configuration - your file structure is your route definition.

## How It Works

The same pattern applies to both API routes and client pages:

```
api/
  index/
    index.ts          -> /api
  users/
    index.ts          -> /api/users
    [id]/
      index.ts        -> /api/users/:id

pages/
  index/
    index.tsx         -> /
  users/
    index.tsx         -> /users
    [id]/
      index.tsx       -> /users/:id
```

The parallel structure between `api/` and `pages/` is intentional -
if you have a `/users/[id]` page, the corresponding `/api/users/[id]` endpoint is easy to find.

Every route lives in a folder, including the root - the base route uses a folder named `index`.
This consistency means no special cases: every route is a folder with an `index` file inside.

## Route File Requirements

API routes export a route definition (HTTP methods + handlers).
Client pages export a component function.

When you create a new route, you rarely write it from scratch -
it is automatically seeded with the correct boilerplate.

The folder-per-route pattern gives each route its own namespace for colocating related files -
utilities, types, tests - without cluttering parent directories.

## Nested Routes

Nesting works by nesting folders. `api/users/[id]/posts/index.ts` maps to `/api/users/:id/posts`,
and can go as deep as your domain requires. Each level can colocate its own helpers,
types, and tests without affecting siblings.

For client pages, nested routes support layout components that wrap child routes
with shared UI like navigation or headers.
[Details ›](/frontend/routing)

## Native Routing Under the Hood

A fair question: with custom parameter syntax and `path-to-regexp` patterns,
is KosmoJS running its own router at runtime? It isn't.

`path-to-regexp` is used only at build time, to parse your directory structure into
route definitions. At runtime, those parsed routes are registered with each framework's
**native router** - exactly as you would register them by hand. Nothing sits between a
request and your framework's matching logic.

```
build time                          runtime
──────────                          ───────
directory structure                 native router registration
  api/users/[id]/index.ts    ->        Hono/H3/Koa router
  pages/users/[id]/index.tsx ->        React/Solid/Vue router
        │                                       │
        └── parsed via path-to-regexp ──────────┘
```

The payoff is that you keep the full, native routing of whatever framework you chose -
nothing is wrapped, shimmed, or reimplemented:

* **Backend** - Hono/H3/Koa router handles your routes natively.
* **Frontend** - React Router, Solid Router, and Vue Router each receive standard route
  definitions, so nested layouts, lazy loading, loaders/preloads, and navigation guards
  all behave exactly as documented by those frameworks.

**KosmoJS is the chassis, not the engine.**

It gives every source folder the same consistent, directory-based way to define routes;
the engine doing the actual routing is the framework you picked.

---

---
url: /routing/rationale.md
description: >-
  Understanding why directory-based routing scales better than file-based
  routing for organizing large applications with clear navigation,
  colocalization, and visual hierarchy.
---

At first glance, directory-based routing looks more verbose than file-based alternatives.
`api/users/[id]/index.ts` vs `api/users/[id].ts` - the extra folder seems unnecessary.
It isn't, and the reason becomes obvious as your project grows.

## The File-Based Routing Problem

In file-based routing, route handlers and helper files live side by side:

```
api/
  users/
    index.ts           -> Handler for /users
    [id].ts            -> Handler for /users/:id
    schema.ts          -> Validation schemas... for which route?
    auth.ts            -> Authorization... for which endpoint?
    utils.ts           -> Helpers... used by what?
```

Which files are route handlers? Which are helpers? Is `schema.ts` a route at `/users/schema`
or a shared validation file? You can't tell without opening each file or relying on team conventions.

## Directory-Based Clarity

With directory-based routing, the rule is simple: **only `index.ts` is a route handler**.
Everything else in the folder is a helper for that route.

```
api/
  users/
    index.ts           -> Handler for /users
    schema.ts          -> Obviously a helper for /users

    [id]/
      index.ts         -> Handler for /users/:id
      permissions.ts   -> Obviously a helper for this endpoint

      posts/
        index.ts       -> Handler for /users/:id/posts
        formatter.ts   -> Obviously post-specific logic
```

No conventions to memorize, no ambiguity. The folder tree is your API map -
every folder with an `index.ts` is a route, everything else is support code.

This scales naturally:

```
api/
  products/
    index.ts
    [id]/
      index.ts
      cache.ts
      pricing.ts
      reviews/
        index.ts
        moderation.ts
        [reviewId]/
          index.ts
          flags.ts
```

Each route's complexity is isolated in its own folder.
New developers understand the structure immediately.
Six months later, you can still navigate it without re-reading the codebase.

## The Trade-off

You create a folder even when it only contains `index.ts`. That's the entire cost.

In return: zero ambiguity, natural colocalization, room to grow without restructuring,
and a folder tree that directly mirrors your API surface:

```sh
$ tree -d src/front/api
src/front/api/
└── shop
    ├── cart
    ├── [category]
    │   └── {productId}
    ├── checkout
    │   ├── confirm
    │   ├── payment
    │   └── shipping
    ├── orders
    │   └── [orderId]
    └── products
        └── {category}
```

---

---
url: /routing/params.md
description: >-
  Handle dynamic URL segments with required [id], optional {id} and splat
  {...path} parameters. SolidStart-inspired syntax that works identically for
  API routes and client pages.
---

Parameter types supported out of the box, with same syntax for both API and client pages:

| Syntax      | Type     | Matches                |
|-------------|----------|------------------------|
| `[id]`      | Required | Exactly one segment    |
| `{id}`      | Optional | One segment or nothing |
| `{...path}` | Splat    | Any number of segments |

## Required Parameters

```
users/[id]/index.ts   -> /users/123, /users/abc
```

The parameter name becomes the key in `ctx.validated.params` (or your framework's equivalent).
`[id]` gives you `params.id`, `[userId]` gives you `params.userId`.

## Optional Parameters

```
users/{id}/index.ts   -> /users and /users/123
```

Useful for combining list and detail views in a single handler,
branching on whether the parameter is present.

**Important:** optional parameters must not be followed by required parameters.

```
users/{section}/{subsection}  ✅
users/{optional}/[required]   ❌
```

### Watch Out for Ambiguous Paths

Optional parameters followed by static segments can cause unexpected 404s:

```
properties/{city}/filters/index.tsx
```

Visiting `/properties/filters`: the router matches `{city}` = `"filters"`,
then expects another `/filters` segment - which isn't there. Result: 404.

Fix it by adding an explicit static route:

```
properties/
├── filters/index.tsx          -> /properties/filters
└── {city}/
    └── filters/index.tsx      -> /properties/NY/filters
```

Static routes always take priority over dynamic ones.

### Required vs Optional - a Subtlety

`[id]` technically means "required at this URL position", but a sibling `index` file changes that:

```
careers/
├── index.tsx       -> /careers (fallback when no id)
└── [jobId]/
    └── index.tsx   -> /careers/123
```

When a parent `index` exists, `[jobId]` is effectively optional - there's a fallback to render.
In this case, `{jobId}` communicates intent more clearly and both notations work identically.

## Splat Parameters

```
docs/{...path}/index.ts   -> /docs/getting-started
                          -> /docs/api/reference
                          -> /docs/guides/deployment/production
```

The matched segments are provided as an array - useful for doc sites, file browsers,
or anything with arbitrarily nested paths.

A request to `/docs/guides/deployment/production` gives you
`params.path` as `["guides", "deployment", "production"]`.

## Mixed Segments

Segments can combine static text with parameters:

```
products/[category].html      -> /products/electronics.html
profiles/[id]-[data].json     -> /profiles/1-posts.json
files/[name].[ext]            -> /files/document.pdf
```

Mixed segments support varies by framework:

* **Hono/H3** - partial support, with caveats
* **Koa** - full support
* **Vue, Svelte and MDX** - full support
* **React Router** - `.ext` suffix only
* **SolidJS Router** - not supported

Prefer simple segments for frontend routes.
[Full support matrix ›](/essentials/frameworks#routing-syntax-support)

## Power Syntax

For advanced cases, KosmoJS passes `path-to-regexp v8` patterns through directly.

> **The rule:** if the param name contains non-alphanumeric characters,
> it is treated as a raw pattern.

This unlocks things like optional static parts:

```
products/{:category.html}
```

* `/products` ✅ (no category, no `.html`)
* `/products/electronics.html` ✅
* `/products/electronics` ❌ (`.html` required when category is present)

More examples:

```
book{-:id}-info           -> /book-info or /book-123-info
locale{-:lang{-:country}} -> /locale, /locale-en, /locale-en-US
api/{v:version}/users     -> /api/users or /api/v2/users
```

::: info Limited support across frameworks
Power Syntax fully works with Koa routes only. Hono will match that routes
but params will be registered using positional index + a hash, e.g. `_0abc` or `_1xyz`.
H3 won't match any of these routes. For client pages use simple segments instead.
:::

---

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

```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()`. The callback hands you the **native** Hono/H3/Koa instance - this is where the error handler is registered and where [app middleware](/backend/middleware#app-middleware) or any framework plugin goes. | Adding app middleware; enabling [debug](/dev-build-run/development-workflow#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 hooks: `requestHandler()` returns the handler the dev server dispatches to (override it for WebSockets or custom dispatch), and `teardownHandler()` runs **before every reload** - close DB connections and sockets here or they leak across restarts. | WebSockets; connection 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) - 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#slot-composition). | Typing `ctx.state` / bindings |

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

#### Foundation files - Hono

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

#### Foundation files - H3

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

#### Foundation files - Koa

```ts
// Koa: api/app.ts
export default appFactory(routes, ({ 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) 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 `lib/`, is git-ignored, and you neither read nor edit it.
[Details ›](/essentials/why-codegen)

## 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 `lib/`, keyed by route name:

```ts [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#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) 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) 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)

## Middleware

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

---

---
url: /backend/context.md
description: >-
  Learn about KosmoJS's enhanced context - unified bodyparser and metaparser
  APIs, and ctx.validated for type-safe validated data access
---

KosmoJS extends the standard Hono/H3/Koa context with three additions:
unified `bodyparser` and `metaparser` APIs, and `ctx.validated` for type-safe access to validated request data.

## Unified Bodyparser

`ctx.bodyparser` works the same regardless of framework:

```ts
await ctx.bodyparser.json()   // JSON request body
await ctx.bodyparser.form()   // URL-encoded or multipart form
await ctx.bodyparser.raw()    // raw body buffer
```

Results are cached - calling the same parser multiple times doesn't re-parse the request.

In practice you rarely call this directly. Define a validation schema in your handler
and the appropriate parser runs automatically, placing the result in `ctx.validated`.

## Unified Metaparser

`ctx.metaparser` does the same for request metadata:

```ts
ctx.metaparser.params()    // route params, normalized
ctx.metaparser.query()     // query parameters, normalized
ctx.metaparser.headers()   // headers, as a plain object
ctx.metaparser.cookies()   // parsed cookies
```

These are synchronous - there is nothing to await - and cached the same way.

`params()` and `query()` hand back normalized values rather than raw strings:
splat params are split into arrays, and values are coerced to match your declared types -
numbers for params, numbers and booleans for query. `headers()` and `cookies()` are plain parses.

***

Both `ctx.metaparser` and `ctx.bodyparser` are rarely used in handlers directly.
They are most useful in [edge middleware](/backend/edge-middleware)
and in a [custom validator](/backend/middleware#overriding-validation).
where `ctx.validated.*` is not filled yet.

They are not there in [`api/app.ts`](/backend/middleware#app-middleware),
which runs before the context is extended.

## Validated Data Access

`ctx.validated` holds the validated, typed result for each target you defined:

```ts
export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: Payload<CreateUser>,
    query: { limit: number },
    headers: { "x-api-key": string },
  }>(async (ctx) => {
    const user = ctx.validated.json;      // validated JSON body
    const limit = ctx.validated.query;    // validated query params
    const apiKey = ctx.validated.headers; // validated headers
  }),
]);
```

## Route Parameters

Validated params are available at `ctx.validated.params`, typed according to your refinements:

```ts [api/users/[id]/index.ts]
export default defineRoute<"users/[id]", [number]>(({ GET, POST }) => [
  GET<{
    query: { page: string; filter?: string },
  }>(async (ctx) => {
    const { id } = ctx.validated.params;    // number
    const { page, filter } = ctx.validated.query;
  }),

  POST<{
    json: Payload<User>,
  }>(async (ctx) => {
    const { id } = ctx.validated.params;    // number
    const user = ctx.validated.json;
  }),
]);
```

`ctx.metaparser.params()` gives you the same normalized values before validation runs -
useful in [edge middleware](/backend/edge-middleware), where `ctx.validated` is still empty.

The underlying raw params still exist if you need them:

* Hono - `ctx.req.param()`
* H3 - `event.context.params`
* Koa - `ctx.params`

---

---
url: /backend/type-safety.md
description: >-
  Refine params/payload/response types in KosmoJS with compile-time TypeScript
  checking and automatic runtime validation using type arguments
---

Type safety in KosmoJS covers the full request-response cycle:
path parameters, payloads, responses, and context/state properties -
all driving both compile-time checking and runtime validation from the same type definitions.

## Typing Params

Parameters are strings by default. Refine them via the second type argument to `defineRoute`
by providing a tuple where each position maps to the corresponding parameter in the path:

```ts [api/users/[id]/{action}/index.ts]
type UserAction = "retrieve" | "update" | "delete";

export default defineRoute<"users/[id]/{action}", [
  number,      // id
  UserAction,  // action
]>(({ GET }) => [
  GET(async (ctx) => {
    const {
      id,     // number
      action, // UserAction | undefined
    } = ctx.validated.params;
  }),
]);
```

Positions are optional - but to refine the second param you must also provide the first.

### ❗ Keep the Tuple Brackets Literal

The refinement tuple's `[]` must be written inline. Type aliases used *inside* it are fine;
extracting the whole tuple to a named type is not:

```ts
// ✅ works - brackets literal, contents aliased
defineRoute<"[id]/[action]", [UserID, UserAction]>

// ❌ won't work - the brackets themselves are behind an alias
type Params = [UserID, UserAction];
defineRoute<"[id]/[action]", Params>
```

The position is read structurally from the source, mapping each slot to a route parameter,
so an alias leaves nothing to destructure.
It fails silently: the schema does not build and **every** request is rejected.

The same rule covers the `response` tuple and the `VRefine` constraint object.
[The bracket rule ›](/validation/refine#keep-the-wrapping-brackets-literal)

Refinements also drive runtime validation - invalid params are rejected before your handler runs.
[Details ›](/validation/params)

## Typing Payload and Response

The first type argument to each method handler defines payload and response schemas:

```ts [api/example/index.ts]
import type { User } from "~/types";

export default defineRoute<"example">(({ POST }) => [
  POST<{
    json: { name: string; email: string; status?: string },
    response: [200, "json", User],
  }>(async (ctx) => {
    const { name, email, status } = ctx.validated.json;
    const user = await createUser({ name, email, status });

    // return ctx.json(user);   // Hono
    // return user              // H3
    // ctx.body = user;         // Koa
  }),
]);
```

Both payload and response are validated at runtime, not just at compile time.
[Details ›](/validation/payload)

## Typing State & Context

`defineRoute` accepts four type arguments:

### Typing State & Context - Hono

```ts
// Hono: api/users/[id]/index.ts
defineRoute<
  "route-name",
  ParamsTuple,      // param refinements
  Variables,        // route-specific locals
  Bindings,         // route-specific bindings
>
```

### Typing State & Context - H3

```ts
// H3: api/users/[id]/index.ts
defineRoute<
  "route-name",
  ParamsTuple,      // param refinements
  Context,          // route-specific context properties
>
```

### Typing State & Context - Koa

```ts
// Koa: api/users/[id]/index.ts
defineRoute<
  "route-name",
  ParamsTuple,      // param refinements
  State,            // route-specific state/locals
  Context,          // route-specific context properties
>
```

### Typing State & Context (cont.)

Use the third and fourth arguments for types that are unique to a specific route:

### Typing State & Context - Hono

```ts
// Hono: api/users/[id]/index.ts
export default defineRoute<
  "users/[id]",
  [number],
  { permissions: Array<"read" | "write"> },  // ctx.get("permissions")
  { DB: D1Database },                        // Cloudflare binding
>(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.validated.params;
    const permissions = ctx.get("permissions");
    const db = ctx.env.DB;
  }),
]);
```

### Typing State & Context - H3

```ts
// H3: api/users/[id]/index.ts
export default defineRoute<
  "users/[id]",
  [number],
  { permissions: Array<"read" | "write"> },  // event.context.permissions
>(({ GET }) => [
  GET(async (event) => {
    const { id } = event.validated.params;
    const { permissions } = event.context;
  }),
]);
```

### Typing State & Context - Koa

```ts
// Koa: api/users/[id]/index.ts
export default defineRoute<
  "users/[id]",
  [number],
  { permissions: Array<"read" | "write"> },  // ctx.state.permissions
  { authorizedUser: User },                  // ctx.authorizedUser
>(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.validated.params;
    const { permissions } = ctx.state;
    const { authorizedUser } = ctx;
  }),
]);
```

### Typing State & Context (cont.)

If you find yourself declaring the same properties across many routes,
move them to the global declarations in `api/env.d.ts` instead -
a `declare module "_/api"` augmentation rather than a `defineRoute` type argument.

## Global Context Types - `api/env.d.ts`

`api/env.d.ts` extends the default context and state interfaces globally,
so every route handler picks them up automatically:

### Global Context Types - `api/env.d.ts` - Hono

```ts
// Hono: api/env.d.ts
export declare module "_/api" {
  interface DefaultVariables {
    permissions: Array<"read" | "write" | "admin">;
  }
  interface DefaultBindings {
    DB: D1Database;
  }
}
```

### Global Context Types - `api/env.d.ts` - H3

```ts
// H3: api/env.d.ts
export declare module "_/api" {
  interface DefaultContext {
    permissions: Array<"read" | "write" | "admin">;
  }
}
```

### Global Context Types - `api/env.d.ts` - Koa

```ts
// Koa: api/env.d.ts
export declare module "_/api" {
  interface DefaultState {
    permissions: Array<"read" | "write" | "admin">;
  }
  interface DefaultContext {
    authorizedUser: User;
  }
}
```

### Global Context Types - `api/env.d.ts` (cont.)

> **Important:** declaring types in `env.d.ts` doesn't set the values -
> you still need the middleware that actually populates them.

The right place to set global properties is `api/use.ts` file.
It runs for every endpoint, so properties becomes available for all routes:

### Global Context Types - `api/env.d.ts` - Hono

```ts
// Hono: api/env.d.ts
import { use } from "_/api";

export default [
  use(async (ctx, next) => {
    ctx.set("permissions", await getPermissions(ctx)); // [!code hl]
    return next();
  }),
];
```

### Global Context Types - `api/env.d.ts` - H3

```ts
// H3: api/env.d.ts
import { use } from "_/api";

export default [
  use(async (event, next) => {
    event.context.permissions = await getPermissions(ctx);  // [!code hl]
    return next();
  }),
];
```

### Global Context Types - `api/env.d.ts` - Koa

```ts
// Koa: api/env.d.ts
import { use } from "_/api";

export default [
  use(async (ctx, next) => {
    ctx.state.permissions = await getPermissions(ctx);  // [!code hl]
    return next();
  }),
];
```

### Global Context Types - `api/env.d.ts` (cont.)

---

---
url: /backend/middleware.md
description: >-
  Middleware chains and the Hono/H3/Koa onion model. Global middleware in
  api/use.ts that runs for every route in a source folder, method restrictions,
  and overriding defaults through slots.
---

Beyond the standard HTTP method handlers, you often need to run custom middleware -
code that executes before your main handler to perform tasks like authentication,
logging, or data transformation.

## Basic Usage

KosmoJS provides the `use` function for applying middleware.
The same API applies identically to all frameworks, only the middleware internals slightly differs by framework:

```ts [api/example/index.ts]
export default defineRoute<"example">(({ GET, POST, use }) => [
  use(async (ctx, next) => {
    // runs for both GET and POST
    return next();
  }),

  GET(async (ctx) => { /* ... */ }),
  POST(async (ctx) => { /* ... */ }),
]);
```

Middleware must call `next()` to pass control to the next layer.
Skipping `next()` short-circuits the chain - useful for early rejections.

## Execution Order (Onion Model)

Middleware runs in definition order going in, then unwinds in reverse after the handler.

Consider this example:

```ts [api/example/index.ts]
export default defineRoute<"example">(({ POST, use }) => [
  use(async (ctx, next) => {
    console.log("First middleware");
    await next();
    console.log("First middleware after next");
  }),

  use(async (ctx, next) => {
    console.log("Second middleware");
    await next();
    console.log("Second middleware after next");
  }),

  POST(async (ctx) => {
    console.log("POST handler");
    // ...
  }),
]);
```

When a POST request arrives, the execution order is like:

```
First middleware
Second middleware
POST handler
Second middleware after next
First middleware after next
```

> **Positioning note:** All `use` calls run before method handlers regardless of where they appear in the array.
> Defining `use` after a handler doesn't change this:

```ts
export default defineRoute<"example">(({ use, GET, POST }) => [
  use(firstMiddleware),
  GET(async (ctx) => { /* ... */ }),
  POST(async (ctx) => { /* ... */ }),
  use(secondMiddleware), // still runs BEFORE handlers [!code hl]
]);
```

## Global Middleware

Wiring same middleware into every route is tedious and dangerous.

Use **global middleware** instead - add middleware to `api/use.ts` and it runs for **every route** -
no imports, no registration, nothing to wire:

### Global Middleware - Hono

```ts
// Hono: api/use.ts
import { use } from "_/api";

export default [
  // will run on every route
  use(async function requestId(ctx, next) {
    ctx.set("requestId", crypto.randomUUID());
    return next();
  }),
];
```

### Global Middleware - H3

```ts
// H3: api/use.ts
import { use } from "_/api";

export default [
  // will run on every route
  use(async function requestId(event, next) {
    event.context.requestId = crypto.randomUUID();
    return next();
  }),
];
```

### Global Middleware - Koa

```ts
// Koa: api/use.ts
import { use } from "_/api";

export default [
  // will run on every route
  use(async function requestId(ctx, next) {
    ctx.state.requestId = crypto.randomUUID();
    return next();
  }),
];
```

### Global Middleware (cont.)

This is the place for work that belongs to **routes**: loading the current user onto the context,
permission checks, audit logging of writes - things that need a route to exist,
and that want the request already validated.

Anything narrower belongs in a [cascading use.ts](/backend/cascading-middleware) for a subtree, or in the route's own `use`.

::: warning `api/use.ts` is skipped for non-route responses
A preflight `OPTIONS`, or a `405` for a method the route doesn't implement,
is answered before any route chain runs - so global middleware never sees it.

Which makes this the wrong home for **CORS**: the preflight would never reach your middleware,
and the browser would reject the request before it ever sent the real one.

CORS - and anything else that must appear on *every* response - belongs to [app middleware](#app-middleware).
:::

## Method-Specific Middleware

Use the `on` option to restrict middleware to specific HTTP methods:

### Method-Specific Middleware - Hono

```ts
// Hono: api/example/index.ts
export default defineRoute<"example">(({ GET, POST, use }) => [
  use(async (ctx, next) => {
    ctx.set("user", await verifyToken(ctx.req.header("authorization")));
    return next();
  }, {
    on: ["POST"], // [!code hl]
  }),

  GET(async (ctx) => {
    // no auth required
  }),

  POST(async (ctx) => {
    // ctx.get("user") is available
  }),
]);
```

### Method-Specific Middleware - H3

```ts
// H3: api/example/index.ts
export default defineRoute<"example">(({ GET, POST, use }) => [
  use(async (event, next) => {
    event.context.user = await verifyToken(event.req.headers.get("authorization"));
    return next();
  }, {
    on: ["POST"], // [!code hl]
  }),

  GET(async (event) => {
    // no auth required
  }),

  POST(async (event) => {
    // event.context.user is available
  }),
]);
```

### Method-Specific Middleware - Koa

```ts
// Koa: api/example/index.ts
export default defineRoute<"example">(({ GET, POST, use }) => [
  use(async (ctx, next) => {
    ctx.state.user = await verifyToken(ctx.headers.authorization);
    return next();
  }, {
    on: ["POST"], // [!code hl]
  }),

  GET(async (ctx) => {
    // no auth required
  }),

  POST(async (ctx) => {
    // ctx.state.user is available
  }),
]);
```

## Slot Composition

Slots are named positions in the middleware chain. Middleware with the same slot name
replaces earlier middleware at that position - useful for overriding global defaults per-route.

A global logger defined in `api/use.ts`:

```ts [api/use.ts]
export default [
  use(
    async (ctx, next) => { /* global logger */ },
    { slot: "logger" },
  ),
];
```

Override it for a specific route:

```ts [api/upload/index.ts]
export default defineRoute<"upload">(({ POST, use }) => [
  use(
    async (ctx, next) => {
      // custom logger for this route only
    },
    { slot: "logger" },
  ),
  POST(async (ctx) => { /* ... */ }),
]);
```

> When overriding via slot, explicitly set [on](#method-specific-middleware) option if needed -
> it doesn't inherit from the middleware being replaced.

Custom slot names, like `logger`, should be added to `api/env.d.ts`:

```ts [api/env.d.ts]
export declare module "_/api" {
  // ...
  interface UseSlots {
    logger: string; // [!code hl]
  }
}
```

Then use it anywhere:

```ts
use(async (ctx, next) => { /* ... */ }, { slot: "logger" })
```

Some slot names are reserved and already positioned in the chain -
the [`edge:`](/backend/edge-middleware) family is the one you are likely to reach for.

***

### Promoting to the Route Edge

Any `use()` entry claiming an `edge:` prefixed slot in `api/use.ts`, in a cascading `use.ts`, or in the route itself -
is lifted out of its usual position and run first in the matched route's chain instead, ahead of validation.
That is [edge middleware](/backend/edge-middleware).

## Overriding Validation

Validation is middleware too, and every target sits in a reserved slot -
so any of them can be replaced exactly the way you replace a `logger`.

Available validation slots, each reserved for a specific validation target:

```
validate:params
validate:query
validate:headers
validate:cookies
validate:json
validate:form
validate:raw
validate:response
```

> These are reserved slots - no `UseSlots` declaration in `api/env.d.ts` needed.

Claim one and your middleware runs **instead of** the built-in validator for that target,
say an endpoint accepts a body no schema can describe:

```ts [api/import/index.ts]
export default defineRoute<"import">(({ POST, use }) => [
  use(async (ctx, next) => {
    // NDJSON - one JSON document per line
    const body = await ctx.bodyparser.raw<string>();
    // ...
    return next();
  }, {
    slot: "validate:json", // [!code hl]
  }),

  POST(async (ctx) => { /* ... */ }),
]);
```

Everything else about slots still applies: declare it in `api/use.ts` to replace validation
folder-wide, in a [cascading use.ts](/backend/cascading-middleware) for a subtree,
or in the route itself for one endpoint.

### What You Take Over

One target, and only that one. Overriding `validate:json` replaces the JSON validator and
nothing else - `ctx.validated.params`, `.query`, `.headers` and `.cookies` are still filled
in by their own validators, still before your handler runs.

What you give up is that target's entry in `ctx.validated`. The built-in validator loads the
data, checks it, and publishes the result; yours is only expected to check. So
`ctx.validated.json` stays unset, and the handler reads the body itself.

Which costs nothing, because the parsers are shared:

::: tip Parsers are lazy and cached
`ctx.bodyparser.<target>()` and `ctx.metaparser.<target>()` each run at most once per
request and return the cached result afterwards. Call them wherever you like - in your
validator, in the handler, in both. The request stream is read once no matter how many
times you ask for it.
:::

So the handler above just asks again, and gets the body your validator already parsed:

```ts [api/import/index.ts]
  POST(async (ctx) => {
    const records = await ctx.bodyparser.raw<string>()
    // ...
  }),
```

Overriding `validate:response` works the same way in reverse: your middleware decides what
a valid response looks like, and the built-in check no longer runs.

## App Middleware

The outermost layer, and the only one KosmoJS doesn't compose for you.
`api/app.ts` hands you the `Hono` / `H3` / `Koa` instance itself, so anything the framework can do at app level,
you do here - written exactly as that framework's own docs describe:

### App Middleware - Hono

```ts
// Hono: api/app.ts
import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";

export default appFactory(routes, ({ app }) => {
  app.onError(defaultErrorHandler);

  app.use(async (c, next) => {
    const started = performance.now();
    await next();
    console.log([ c.req.method, c.req.path, performance.now() - started ]);
  });
});
```

### App Middleware - H3

```ts
// H3: api/app.ts
import { onError } from "h3";

import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";

export default appFactory(routes, ({ app }) => {
  app.use(onError(defaultErrorHandler));

  app.use(async (event, next) => {
    const started = performance.now();
    await next();
    console.log([ event.req.method, event.url.pathname, performance.now() - started ]);
  });
});
```

### App Middleware - Koa

```ts
// Koa: api/app.ts
import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";

export default appFactory(routes, ({ app }) => {
  app.use(defaultErrorHandler);

  app.use(async (ctx, next) => {
    const started = performance.now();
    await next();
    console.log([ ctx.method, ctx.path, performance.now() - started ]);
  });
});
```

### App Middleware (cont.)

This layer runs **first, on every request**, whether or not a route matched -
so it is the only place that can answer a 404, or see traffic for URLs your `api/` tree knows nothing about.

It is also the bluntest layer. There are no slots here and nothing downstream can replace it,
and KosmoJS doesn't compose it.

It runs before any route chain, so the KosmoJS helpers aren't on the context yet:
no `ctx.validated`, no `ctx.metaparser`, no `ctx.bodyparser`.

Read the request through the framework's own API - or move the check into [edge middleware](/backend/edge-middleware),
which runs inside the route's chain and has them.

Request logging, CORS, tracing, rate limiting by IP: things that are true of the connection rather than of the route.

---

---
url: /backend/cascading-middleware.md
description: >-
  Organize middleware hierarchically using use.ts files that wrap route
  subtrees. Apply authentication, logging, and custom parsers to folders and
  their descendants without cluttering individual route definitions.
---

Place a `use.ts` file in any folder, and its middleware automatically wraps all routes
in that folder and its subfolders - no imports or wiring required.

## How it Works

```txt
api/users/
├── about/
│   └── index.ts
├── account/
│   ├── index.ts
│   └── use.ts
├── index.ts
└── use.ts
```

* `users/use.ts` wraps all routes under `/api/users`
* `users/account/use.ts` wraps only routes under `/api/users/account`

Execution order for a request to `/api/users/account`:

```txt
api/use.ts               -> global middleware
users/use.ts             -> parent folder
users/account/use.ts     -> current folder
users/account/index.ts   -> route handler
```

Parent middleware always runs before child middleware.

> Child routes can't skip parent `use.ts`

The seeded boilerplate when you create a `use.ts` in an `api/` subfolder:

```ts [api/users/use.ts]
import { use } from "_/api";

export type UseT = {};

export default [
  use<UseT>(async (ctx, next) => {
    return next();
  })
];
```

> Some editors load the seeded content immediately, others require a brief unfocus/refocus.

Beside the default exported middleware, every `use.ts` **in an `api/` subfolder** exports the `UseT` type - even if empty.
This type extends the context for all routes underneath, giving you automatic type safety for anything the middleware adds.

The global `api/use.ts` is the exception: it may export `UseT`, but the export is ignored there -
global middleware types come from `api/env.d.ts` instead.

## Type-Safe Context Extension

The whole point of cascading middleware is to avoid manual wiring.
That applies to types too - if your auth middleware adds `user` to the context,
every route underneath should know about it without importing or declaring anything.

`UseT` makes this work. Define what your middleware adds:

### Type-Safe Context Extension - Hono

```ts
// Hono: api/users/use.ts
import { use } from "_/api";

export type UseT = {
  user: { id: number; role: "admin" | "user" };
};

export default [
  use<UseT>(async (ctx, next) => {
    const token = ctx.req.header("authorization")?.replace("Bearer ", "");
    // validate before adding to context - UseT promises this property exists
    if (!token) throw new HTTPException(401, { message: "Authentication required" });
    ctx.set("user", await verifyToken(token));
    return next();
  })
];
```

### Type-Safe Context Extension - H3

```ts
// H3: api/users/use.ts
import { use } from "_/api";

export type UseT = {
  user: { id: number; role: "admin" | "user" };
};

export default [
  use<UseT>(async (event, next) => {
    const token = event.req.headers.get("authorization")?.replace("Bearer ", "");
    // validate before adding to context - UseT promises this property exists
    if (!token) throw new HTTPError({ status: 401, message: "Authentication required" });
    event.context.user = await verifyToken(token);
    return next();
  })
];
```

### Type-Safe Context Extension - Koa

```ts
// Koa: api/users/use.ts
import { use } from "_/api";

export type UseT = {
  user: { id: number; role: "admin" | "user" };
};

export default [
  use<UseT>(async (ctx, next) => {
    const token = ctx.headers.authorization?.replace("Bearer ", "");
    // validate before adding to state - UseT promises this property exists
    ctx.assert(token, 401, "Authentication required");
    ctx.state.user = await verifyToken(token);
    return next();
  })
];
```

### Type-Safe Context Extension (cont.)

Now every route under `/api/admin` has `user` typed on the context automatically -
no imports, no type arguments on `defineRoute`:

### Type-Safe Context Extension - Hono

```ts
// Hono: api/users/use.ts
export default defineRoute<"admin/dashboard">(({ GET }) => [
  GET(async (ctx) => {
    const user = ctx.get("user");  // typed as { id: number; role: "admin" | "user" }
  }),
]);
```

### Type-Safe Context Extension - H3

```ts
// H3: api/users/use.ts
export default defineRoute<"admin/dashboard">(({ GET }) => [
  GET(async (event) => {
    const { user } = event.context;  // typed as { id: number; role: "admin" | "user" }
  }),
]);
```

### Type-Safe Context Extension - Koa

```ts
// Koa: api/users/use.ts
export default defineRoute<"admin/dashboard">(({ GET }) => [
  GET(async (ctx) => {
    const { user } = ctx.state;  // typed as { id: number; role: "admin" | "user" }
  }),
]);
```

### Type-Safe Context Extension (cont.)

`UseT` is imported from each `use.ts` in the hierarchy and merged into the context type for `defineRoute`.
Inner definitions override outer ones - just like at runtime,
where inner middleware runs after outer middleware and can overwrite context values.

> The global `api/use.ts` does not need to export `UseT`.
> Even if it does, the export is ignored - global middleware operates on types defined in `api/env.d.ts`.
> `UseT` is for `use.ts` files in `api/` subfolders only, where the types cascade alongside the middleware itself.

**Tip:** inner `use.ts` files can import `UseT` from outer ones, extend it, and re-export -
avoiding duplicate type definitions across the hierarchy:

```ts [api/admin/settings/use.ts]
import type { UseT as ParentT } from "../use";

export type UseT = ParentT & {
  settingsAccess: "read" | "write";
};
```

## Parameter Availability

Cascading middleware runs for all routes in the hierarchy, including ones that don't
define the parameters you might expect:

```txt
api/users/
├── [id]/index.ts    ← has 'id' param
├── index.ts         ← NO 'id' param
└── use.ts
```

`ctx.params.id` is undefined for `/users`. Keep cascading middleware generic -
authentication, logging, rate limiting. Parameter-specific logic belongs in the route handler.

## Multiple Middleware + Method Filtering

A single `use.ts` can define multiple functions, and each supports the `on` option
to run only on specific request method(s):

```ts
// api/users/use.ts
import { use } from "_/api";

export type UseT = {
  user: { id: number; name: string };
};

export default [
  use<UseT>(async (ctx, next) => {
    // will run on ANY request method
    return next();
  }),

  use<UseT>(
    async (ctx, next) => {
      // will run only on POST
    },
    { on: ["POST"] },
  ),
];
```

## Common Use Cases

Cascading middleware is where subtree-wide concerns belong: authentication, permission checks,
audit logging, per-section rate limiting.

KosmoJS imposes nothing here - `use` accepts your framework's own middleware signature,
so **any Hono/H3/Koa middleware package works unchanged**.
There is nothing KosmoJS-specific about the middleware itself.

### Third-party middleware

Add middleware to `use.ts` and it will run on every route underneath:

#### Third-party middleware - Hono

```ts
// Hono: api/users/use.ts
import { rateLimiter } from "hono-rate-limiter";

import { use } from "_/api";

export default [
  use(
    rateLimiter({
      windowMs: 15 * 60 * 1000,
      limit: 100,
      keyGenerator: (ctx) => ctx.req.header("x-forwarded-for") ?? "anonymous",
    }),
  ),
];
```

#### Third-party middleware - H3

```ts
// H3: api/users/use.ts
import { use } from "_/api";

export default [
  use(async function noStore(event, next) {
    event.res.headers.set("cache-control", "no-store");
    return next();
  }),
];
```

#### Third-party middleware - Koa

```ts
// Koa: api/users/use.ts
import ratelimit from "koa-ratelimit";

import { use } from "_/api";

const db = new Map();

export default [
  use(ratelimit({ driver: "memory", db, duration: 15 * 60 * 1000, max: 100 })),
];
```

#### Third-party middleware (cont.)

::: warning Not CORS, though
A `use.ts` is composed into each route's chain, so it only runs once a route has matched.
A preflight `OPTIONS` is answered before that, and never reaches it.
CORS belongs in `api/app.ts`, as [app middleware](/backend/middleware#app-middleware).
:::

`api/app.ts` takes a callback receiving the native app instance - not the array of `use()` calls above -
so third-party middleware is registered exactly as that framework documents it:

`cors` below is whatever CORS middleware you wire up - `hono/cors`, `@koa/cors`, or your own header-setting middleware.
What differs per backend is only how the error handler attaches:

#### Third-party middleware - Hono

```ts
// Hono: api/app.ts
import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";
import { cors } from "./cors"; // [!code ++]

export default appFactory(routes, ({ app }) => {
  app.onError(defaultErrorHandler);
  app.use(cors({ origin: "https://example.com" })); // [!code ++]
});
```

#### Third-party middleware - H3

```ts
// H3: api/app.ts
import { onError } from "h3";

import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";
import { cors } from "./cors"; // [!code ++]

export default appFactory(routes, ({ app }) => {
  app.use(onError(defaultErrorHandler));
  app.use(cors({ origin: "https://example.com" })); // [!code ++]
});
```

#### Third-party middleware - Koa

```ts
// Koa: api/app.ts
import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";
import { cors } from "./cors"; // [!code ++]

export default appFactory(routes, ({ app }) => {
  app.use(defaultErrorHandler);
  app.use(cors({ origin: "https://example.com" })); // [!code ++]
});
```

### Authentication for a subtree

Gate a whole section of the API by dropping a `use.ts` into its folder.
Everything under `/api/admin` is now behind the check,
and every route beneath it gets `user` typed on the context through [UseT](#type-safe-context-extension) -
no imports, no type arguments:

```txt
api/
├── use.ts              -> global: request id, auth, rate limit
└── admin/
    ├── use.ts          -> auth: everything under /api/admin
    ├── index.ts
    └── users/
        └── index.ts
```

```ts [api/admin/use.ts]
import { use } from "_/api";

export type UseT = {
  user: { id: number; role: "admin" | "user" };
};

export default [
  use<UseT>(async function requireAdmin(ctx, next) {
    // verify, then populate - UseT promises the property exists downstream
    return next();
  }),
];
```

There is no bundled auth solution and no NextAuth-style integration:
you verify the token and populate the context yourself, the native way for your framework
(`ctx.set("user", ...)` on Hono, `event.context.user = ...` on H3, `ctx.state.user = ...` on Koa).

### Choosing between `use.ts` and route-level `use`

| | Use a cascading `use.ts` | Use an inline `use` |
|---|---|---|
| Scope | a folder and everything beneath it | one route file |
| Wiring | automatic - no imports | explicit, inside `defineRoute` |
| Context types | cascade via `UseT` | via `defineRoute` type arguments |
| Good for | auth, audit logging, rate limiting | one-off concerns for a single endpoint |

Keep cascading middleware **generic**. It runs for sibling routes too,
so a param like `id` may be undefined there - see [Parameter Availability](#parameter-availability).
Parameter-specific logic belongs in the route handler.

---

---
url: /backend/edge-middleware.md
description: >-
  The first middleware a matched route runs - any use() entry under an
  edge-prefixed slot, at any level, ahead of validation, so authentication
  answers 401 before a schema can answer 400.
---

Edge middleware is the first thing a matched route runs - ahead of validation,
ahead of your global, cascading and route middleware.

```
app middleware          <- api/app.ts, every request, matched or not
  edge middleware       <- slot: "edge:*", first in the route's chain
    validation          <- params, query, headers, cookies, body
      global middleware <- api/use.ts
        cascading use.ts
          route use()
            handler
```

::: tip The route's edge
Edge middleware sits at the *route* edge: it goes first once a route has matched, and nothing reaches it otherwise.
[App middleware](/backend/middleware#app-middleware) in `api/app.ts` is what sits at the request edge - it sees every request, matched or not.
:::

## Why It Exists

Validation runs before your middleware - global, cascading and route alike.
Usually that is what you want: your middleware gets a request already known to be well-formed.

For authentication it is exactly wrong.
An expired token on a request that also has a malformed body produces a `400 ValidationError`,
and the caller goes hunting through their payload for a problem that isn't there.
They should have got a `401`.

**Solution: make your auth middleware run before validation by using an `edge:` prefixed slot:**

### Why It Exists - Hono

```ts
// Hono: api/use.ts
import { HTTPError } from "@kosmojs/core/errors";

import { use } from "_/api";

export default [
  use(async (ctx, next) => {
    const token = ctx.req.header("authorization")?.replace("Bearer ", "");
    if (!token) {
      throw new HTTPError([401, "Authentication required"]);
    }
    return next();
  }, {
    slot: "edge:auth", // [!code hl]
  }),
];
```

### Why It Exists - H3

```ts
// H3: api/use.ts
import { HTTPError } from "@kosmojs/core/errors";

import { use } from "_/api";

export default [
  use(async (event, next) => {
    const token = event.req.headers.get("authorization")?.replace("Bearer ", "");
    if (!token) {
      throw new HTTPError([401, "Authentication required"]);
    }
    return next();
  }, {
    slot: "edge:auth", // [!code hl]
  }),
];
```

### Why It Exists - Koa

```ts
// Koa: api/use.ts
import { HTTPError } from "@kosmojs/core/errors";

import { use } from "_/api";

export default [
  use(async (ctx, next) => {
    const token = ctx.headers.authorization?.replace("Bearer ", "");
    if (!token) {
      throw new HTTPError([401, "Authentication required"]);
    }
    return next();
  }, {
    slot: "edge:auth", // [!code hl]
  }),
];
```

### Why It Exists (cont.)

Now an unauthenticated request is rejected before a single schema is consulted.

It is still your middleware, written with `use()` like any other - only its position changes.
It isn't only for auth. Use it for anything that must run before validation - a logger, a rate limiter, a tenant lookup.

Declare it globally in `api/use.ts` and it covers every route.
Declare it in a [cascading use.ts](/backend/cascading-middleware) and it covers a subtree.
Declare it in a route and it runs for that route only.

## Specifics

**Empty `ctx.validated.*`** Validation hasn't run, so nothing has been checked yet.
Use [metaparser](/backend/context#unified-metaparser) / [bodyparser](/backend/context#unified-bodyparser) instead.
They contain normalized data, exactly as the validation routines see it.
Or rely on raw data directly from the framework.

**It is still per route.** Running first doesn't make it [app middleware](/backend/middleware#app-middleware):
a request matching no route never reaches it, and neither do preflights or `405`s.

**It composes.** Because it is a slot, a declaration further down replaces one from above under the
[usual rules](/backend/middleware#slot-composition), keeping the same position -
and a route can declare an `edge:` slot of its own with nothing above it to replace:

```ts [api/webhooks/stripe/index.ts]
export default defineRoute<"webhooks/stripe">(({ POST, use }) => [
  use(async (ctx, next) => {
    // this endpoint authenticates by signature, not by bearer token
    await verifyStripeSignature(ctx);
    return next();
  }, {
    slot: "edge:auth", // [!code hl]
  }),

  POST(async (ctx) => { /* ... */ }),
]);
```

The same works a level up: one `edge:auth` entry in `api/public/use.ts` replaces the global
check for everything in that subtree.

## Name Your Slots

Every `edge:` prefixed name is reserved, so none of them needs a `UseSlots` declaration in `api/env.d.ts`.
Typos are still caught: `edge-auth` is not a slot - and neither is bare `edge` yours to take, per the warning below.

Pick a name per concern and you get as many edge middlewares as you like -
declared here in `api/use.ts`, but any level works:

```ts [api/use.ts]
export default [
  use(rateLimit, { slot: "edge:ratelimit" }), // [!code hl]
  use(authenticate, { slot: "edge:auth" }), // [!code hl]
];
```

They run at the edge in the order declared, and each is its own slot -
so a route can substitute one and leave the others in place.
The Stripe webhook above replaces `edge:auth` with signature verification while `edge:ratelimit` keeps applying to it.

::: warning `edge` itself is reserved - always prefix
The bare `edge` slot is not a spare name. It holds the built-in middleware that extends the context,
and claiming it replaces that: no `ctx.metaparser`, no `ctx.bodyparser`, no `ctx.validated`,
and every validator, middleware and handler downstream that expects them breaks at once.

Name yours `edge:auth`, `edge:ratelimit`, anything prefixed.
Override `edge` only if replacing context extension is exactly what you mean to do,
and you know what has to go back in its place.
:::

## So, Where Do I Add My Auth?

Depends on whether any route needs to opt out.

**Every route authenticates the same way** - put it in `api/app.ts` as [app middleware](/backend/middleware#app-middleware).
It is the simpler setup: one middleware, no slots, nothing downstream can replace it by accident.
It also covers what a route chain never sees - unmatched URLs, preflights, `405`s.

`api/app.ts` hands you the native app instance, so the check is registered the way that framework documents it -
no `use()`, no slot, nothing imported from `_/api`:

### So, Where Do I Add My Auth? - Hono

```ts
// Hono: api/app.ts
import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";

export default appFactory(routes, ({ app }) => {
  app.onError(defaultErrorHandler);

  app.use(async (ctx, next) => {
    const token = ctx.req.header("authorization")?.replace("Bearer ", "");
    if (!token) return ctx.text("Authentication required", 401);
    await next();
  });
});
```

### So, Where Do I Add My Auth? - H3

```ts
// H3: api/app.ts
import { onError } from "h3";

import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";

export default appFactory(routes, ({ app }) => {
  app.use(onError(defaultErrorHandler));

  app.use(async (event, next) => {
    const token = event.req.headers.get("authorization")?.replace("Bearer ", "");
    if (!token) return new Response("Authentication required", { status: 401 });
    return next();
  });
});
```

### So, Where Do I Add My Auth? - Koa

```ts
// Koa: api/app.ts
import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";

export default appFactory(routes, ({ app }) => {
  app.use(defaultErrorHandler);

  app.use(async (ctx, next) => {
    const token = ctx.headers.authorization?.replace("Bearer ", "");
    ctx.assert(token, 401, "Authentication required");
    await next();
  });
});
```

### So, Where Do I Add My Auth? (cont.)

**Some routes authenticate differently** - a webhook verifying a signature, a public health check,
an endpoint behind its own token - use an `edge:` slot, in `api/use.ts` or wherever the check belongs.
You keep the 401-before-400 ordering, and any route or subtree can substitute its own check.

That is a different file with a different shape - an array of `use()` calls, not a callback receiving the app instance:

```ts [api/use.ts]
import { use } from "_/api";

import { authenticate } from "./auth";

export default [
  use(authenticate, { slot: "edge:auth" }),
];
```

::: warning They don't stack
A route claiming `edge:auth` replaces the `edge:auth` entry from `api/use.ts` -
it does **not** replace anything in `api/app.ts`.
If you put the base check in `api/app.ts` and add a route-level `edge:auth` override, they both run
and the route authenticates twice, by two different rules.
Pick either one.
:::

If you're unsure, start in `api/app.ts`. Moving it to the slot later is mostly mechanical - the same handler, wrapped in `use()`.
Moving the other way is not: every route-level `edge:*` override stops overriding anything and starts running in addition.

---

---
url: /backend/error-handling.md
description: >-
  Handle errors gracefully in KosmoJS with customizable error handlers for Hono,
  H3 and Koa. Learn about default error handling, route-level overrides, and
  framework differences.
---

Error handling starts with `api/errors.ts` file, customize it at your needs:

## Default Error Handler

### Default Error Handler - Hono

```ts
// Hono: api/errors.ts
import { accepts } from "hono/accepts";
import { HTTPException } from "hono/http-exception";

import { ValidationError, HTTPError } from "@kosmojs/core/errors";

import { errorHandlerFactory } from "_/api:factory";

export default errorHandlerFactory(async (error, ctx) => {
  if (error instanceof HTTPException) {
    return error.getResponse();
  }

  const [status, message] = Array.isArray(error)
    ? error
    : error instanceof HTTPError
      ? [error.status, error.message]
      : error instanceof ValidationError
        ? [400, `${error.target}: ${error.errorMessage}`]
        : [error.statusCode || 500, error.message];

  const type = accepts(ctx, {
    header: "Accept",
    supports: ["application/json", "text/plain"],
    default: "text/plain",
  });

  return type === "application/json"
    ? ctx.json({ error: message }, status)
    : ctx.text(message, status);
});
```

### Default Error Handler - H3

```ts
// H3: api/errors.ts
import { ValidationError } from "@kosmojs/core/errors";
import { HTTPError } from "h3";

import { errorHandlerFactory } from "_/api:factory";

export default errorHandlerFactory(async (error, event) => {
  const [status, message = "Unknown error occurred"] = Array.isArray(error)
    ? error
    : error instanceof HTTPError
      ? [error.status, error.message]
      : error instanceof ValidationError
        ? [400, `${error.target}: ${error.errorMessage}`]
        : [error.statusCode || 500, error.message];

  const accept = event.req.headers.get("accept");

  return accept?.includes("application/json")
    ? new Response(JSON.stringify({ error: message }), {
        status,
        headers: { "Content-Type": "application/json" },
      })
    : new Response(message, {
        status,
        headers: { "Content-Type": "text/plain" },
      });
});
```

### Default Error Handler - Koa

```ts
// Koa: api/errors.ts
import { HTTPError, ValidationError } from "@kosmojs/core/errors";

import { errorHandlerFactory } from "_/api:factory";

export default errorHandlerFactory(async (ctx, next) => {
  try {
    await next();
  } catch (error: any) {
    const [status, message] = Array.isArray(error)
      ? error
      : error instanceof HTTPError
        ? [error.status, error.message]
        : error instanceof ValidationError
          ? [400, `${error.target}: ${error.errorMessage}`]
          : [error.statusCode || 500, error.message];

    ctx.status = status;

    if (ctx.accepts("json")) {
      ctx.body = { error: message };
    } else {
      ctx.body = message;
    }
  }
});
```

### Default Error Handler (cont.)

It's a regular file - customize it freely. It is then wired into `api/app.ts`:

* *Hono*: `app.onError(defaultErrorHandler)`
* *H3*: `app.use(onError(defaultErrorHandler))`
* *Koa*: `app.use(defaultErrorHandler)`

## Key differences by framework

| Framework | Details       |
|-----------|---------------|
| **Hono** | `app.onError()` catches everything (`await next()` does **not** throw); returns a `Response`. Per‑route behavior by branching inside `app.onError()`. |
| **H3** | `app.use(onError(errorHandler))` captures any thrown error; returns a `Response`, plain object or string. Branch inside `errorHandler` based on `event.url` or other properties. |
| **Koa** | `defaultErrorHandler` is a middleware that wraps `await next()` in a `try`/`catch` and set `ctx.status`/`ctx.body` when errors thrown. |

***

#### Summary

* **Hono** - `onError` is the single entry point; you return a `Response`.
* **H3** - `onError` behaves like Hono's: you return the response directly.
* **Koa** - `await next()` throws. Errors captured in a middleware.

## Let Handlers Fail

The whole point of a central handler is that route code doesn't have to think about error responses.
So don't wrap handler logic in `try`/`catch` just to turn a failure into a response - throw, and let it propagate:

### Let Handlers Fail - Hono

```ts
// Hono: api/users/[id]/index.ts
import { HTTPError } from "@kosmojs/core/errors";

export default defineRoute<"users/[id]", [number]>(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.validated.params;
    const user = await db.users.find(id);

    // ✅ throw - api/errors.ts turns it into a response
    if (!user) throw new HTTPError([404, "User not found"]);

    return ctx.json(user);
  }),
]);
```

### Let Handlers Fail - H3

```ts
// H3: api/users/[id]/index.ts
import { HTTPError } from "@kosmojs/core/errors";

export default defineRoute<"users/[id]", [number]>(({ GET }) => [
  GET(async (event) => {
    const { id } = event.validated.params;
    const user = await db.users.find(id);

    // ✅ throw - api/errors.ts turns it into a response
    if (!user) throw new HTTPError([404, "User not found"]);

    return user;
  }),
]);
```

### Let Handlers Fail - Koa

```ts
// Koa: api/users/[id]/index.ts
import { HTTPError } from "@kosmojs/core/errors";

export default defineRoute<"users/[id]", [number]>(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.validated.params;
    const user = await db.users.find(id);

    // ✅ throw - api/errors.ts turns it into a response
    if (!user) throw new HTTPError([404, "User not found"]);

    ctx.body = user;
  }),
]);
```

### Let Handlers Fail (cont.)

> `HTTPError` takes a single `[status, message]` **tuple**, not two arguments.

```ts
// ❌ don't - the error never reaches api/errors.ts,
//    the status is invented locally, and nothing gets logged centrally
GET(async (ctx) => {
  try {
    // ...
  } catch (error) {
    // ...
  }
});
```

A per-route `catch` costs you three things: the response shape drifts from every other endpoint,
whatever logging/reporting you added to `api/errors.ts` never sees the failure,
and a `ValidationError` caught this way loses its structured `target`/`errors` detail.

`throw` is also how you signal an *expected* failure. The seeded handler understands several shapes:

* `HTTPError` (from `@kosmojs/core/errors`) - status plus message, in every framework.
* Your framework's native error - `HTTPException` (Hono), `HTTPError` (H3), `ctx.throw()`/`ctx.assert()` (Koa).
* A `[status, message]` tuple - the shorthand the seeded handler destructures first.
* `ValidationError` - thrown for you by the validation layer; answered with a 400.
* Anything else - `error.statusCode || 500`.

**Catch inside a handler only when you intend to recover** - falling back to a cached value,
retrying a flaky upstream, or converting a third-party error into a meaningful one.
Then re-throw what you can't handle:

```ts
try {
  // ...
} catch (error) {
  if (error instanceof UpstreamTimeout) {
    // ... real recovery
  }
  throw error; // not ours to handle - let api/errors.ts decide
}
```

The same rule holds for middleware: code after `await next()` runs on the way out,
so wrapping `next()` in `try`/`catch` swallows errors for everything downstream.

Put cross-cutting error concerns in `api/errors.ts` instead - it is a regular file
you own, and it is the one place that sees every failure.

---

---
url: /backend/aliases.md
description: >-
  Serve an existing API route at an additional public URL - well-known paths,
  legacy URLs, and public-facing names that differ from the route on disk.
---

Route names come from the filesystem, which is what makes them predictable.

Occasionally a URL has to be something else: `/feed.xml` rather than `/rss`,
or a path a previous system published that you cannot break.

`alias` in the `backend` block serves an existing route at an additional URL:

```ts [kosmo.config.ts]
export default defineConfig({
  backend: {
    stack: "hono",
    base: "/api",
    alias: {
      "/feed.xml": "rss",
      "/members/[id]": "users/[id]",
    },
  },
});
```

The key is the URL to serve. The value is the name of the route that handles it.

## The key is absolute

An alias URL is **not** prefixed by [backend.base](/essentials/config#backend-base-required).
It is the whole path, from the root of the host:

```ts
backend: {
  base: "/api",
  alias: {
    // served at /feed.xml, not /api/feed.xml
    "/feed.xml": "rss",
  },
}
```

That is the point of the feature - a well-known URL like `/feed.xml` or `/healthz`
usually has to sit outside the API prefix, where a filesystem route could not put it.

## Dynamic segments must match by name

When the alias carries parameters, the target route's parameters must all be present,
with the same names and the same kind. Their **positions may differ**:

```ts
alias: {
  // ok - same parameter, different surrounding path
  "/members/[id]": "users/[id]",

  // ok - same two parameters, reordered
  "/[org]/team/[id]": "orgs/[org]/members/[id]",

  // 404 - target expects "id", alias supplies "userId"
  "/members/[userId]": "users/[id]",

  // 404 - target expects a parameter the alias never supplies
  "/members": "users/[id]",
}
```

A mismatch is not a startup error. The alias is registered and the request 404s,
so check the shape when an alias silently fails to resolve.

## What the alias shares

An alias is another entry pointing at the same route - not a copy of it, and not a redirect.
No `3xx` is issued; the URL the client asked for is the URL it keeps.

The handler is the same function, so everything attached to the route comes with it:
its [middleware](/backend/middleware), the [cascading middleware](/backend/cascading-middleware)
of the directories above it, and its [runtime validation](/validation/intro).
There is nothing to duplicate and nothing that can drift between the two URLs.

## What it does not touch

Aliases are a server-side routing concern only.

The [fetch client](/fetch/intro) is keyed by the route's own name, so client code calls
`fetchClients["users/[id]"]` whichever URL the route also answers on.

The [OpenAPI spec](/openapi) documents the route once, under its route name.

Reach for an alias when an outside consumer needs a particular URL.
For an extra path your own frontend calls, a route file is simpler.

## Supported everywhere

`hono`, `h3` and `koa` all accept `alias`, and the semantics above are identical on each -
only the router pattern the alias compiles to differs.

---

---
url: /backend/custom-templates.md
description: >-
  Override the seeded defineRoute boilerplate for specific API routes using glob
  pattern matching. Seed consistent CRUD endpoints across many routes in Hono,
  H3 and Koa.
---

Every backend generator accepts a `templates` option.
When you create a new route file whose name matches one of your patterns,
**your** boilerplate is written into it instead of the built-in placeholder.

Templates seed route `index` files - `api/**/index.ts` - and nothing else.
Every other seeded file gets the built-in minimal boilerplate to start from.

## Configuration

Pass `templates` through the `backend` block in the source folder's `kosmo.config.ts`,
keyed by route-name pattern:

```ts [kosmo.config.ts]
import { defineConfig } from "@kosmojs/dev";

const crudTemplate = `
import { defineRoute } from "_/api";

export default defineRoute<"{{route.name}}">(({ GET, POST, PUT, DELETE }) => [
  GET(async (ctx) => { /* list or read */ }),
  POST(async (ctx) => { /* create */ }),
  PUT(async (ctx) => { /* update */ }),
  DELETE(async (ctx) => { /* delete */ }),
]);`;

export default defineConfig({
  backend: {
    stack: "hono",
    base: "/api",
    templates: {
      "admin/**": crudTemplate,
    },
  },
});
```

Keys match the **route name** - the path relative to `api/`, without the trailing `index.ts`.
So `api/admin/users/index.ts` is matched as `admin/users`.

## Pattern Syntax

Patterns are [picomatch](https://github.com/micromatch/picomatch) globs matched against the route name.

### Single-depth wildcard (`*`)

```ts
{ "admin/*": template }
```

**Matches:** `admin/users`, `admin/settings`, `admin/[id]`
**Excludes:** `admin/users/roles` (too deep), `admin` (too shallow)

### Multi-depth wildcard (`**`)

```ts
{ "admin/**": template }
```

**Matches:** `admin/users`, `admin/users/roles`, `admin/[id]/audit` - any depth.

### Exact match

```ts
{ "health": template }
```

### Parameter segments are literal

Route parameters are escaped before matching, so `[id]`, `{id}` and `{...path}` mean
themselves rather than glob syntax:

```ts
{
  "users/[id]": userTemplate,           // required parameter
  "products/{category}": productTemplate, // optional parameter
  "docs/{...path}": docsTemplate,        // splat parameter
  "shop/[category]/{sub}": shopTemplate, // combined
}
```

## Resolution Priority

The **first matching pattern wins**, in the order the keys are written - so order them most specific first:

```ts
templates: {
  "admin/audit": auditTemplate,   // exact
  "admin/*": adminTemplate,       // one level
  "**": fallbackTemplate,         // everything else
}
```

A route matching nothing gets the built-in placeholder.
Set `"**"` to replace that default everywhere.

::: warning Numeric-looking patterns jump the queue
JavaScript objects order integer-like keys first, regardless of where you wrote them - so
a pattern such as `"2024/**"` is hoisted to the front and matches before anything above
it. Prefix it with `./` to keep your written order: `"./2024/**"`.
The `./` is stripped before matching.

The same applies to [renderMode](/frontend/server-side-render#selecting-the-render-mode), which uses the same resolver.
:::

## Template Format

A template is either a **string**, or a **function** of the resolved route returning a string -
reach for the function form when the output depends on the route itself:

```ts
templates: {
  // plain string, rendered with Handlebars
  "admin/**": crudTemplate,

  // or computed from the route
  "reports/**": (route) => `
import { defineRoute } from "_/api";

// endpoint: ${route.name}
export default defineRoute<"${route.name}">(({ GET }) => [
  GET(async (ctx) => { /* ... */ }),
]);`,
}
```

String templates are rendered with Handlebars against a `{ route }` context,
so a {{route.name}} placeholder interpolates the route name -
which is what keeps the required [route-name type argument](/backend/intro#the-route-name-type-argument) correct in seeded files.

### Per-backend shapes

Because the context API differs by backend, so does the boilerplate:

#### Per-backend shapes - Hono

```ts
// Hono: kosmo.config.ts
const template = `
import { defineRoute } from "_/api";

export default defineRoute<"{{route.name}}">(({ GET }) => [
  GET(async (ctx) => {
    // Always \`return\` the response
    return ctx.json({ ok: true });
  }),
]);`;
```

#### Per-backend shapes - H3

```ts
// H3: kosmo.config.ts
const template = `
import { defineRoute } from "_/api";

export default defineRoute<"{{route.name}}">(({ GET }) => [
  GET(async (event) => {
    // return the value directly - objects serialize as JSON
    return { ok: true };
  }),
]);`;
```

#### Per-backend shapes - Koa

```ts
// Koa: kosmo.config.ts
const template = `
import { defineRoute } from "_/api";

export default defineRoute<"{{route.name}}">(({ GET }) => [
  GET(async (ctx) => {
    ctx.body = { ok: true };
  }),
]);`;
```

#### Per-backend shapes (cont.)

> Escape backticks (`` \` ``) and `${...}` inside template literals
> that you do not want interpolated at config-evaluation time.

## Seeding CRUD Endpoints

This is where route templates earn their place. Standing up endpoints for a dozen
database tables means writing the same skeleton a dozen times -
validation targets, method handlers, error shape, all identical apart from the type.

Write it once:

```ts [kosmo.config.ts]
const resourceTemplate = `
import { defineRoute } from "_/api";
import type { Resource, ResourcePayload } from "./types";

export default defineRoute<"{{route.name}}">(({ GET, POST }) => [
  GET<{
    query: { page?: number; limit?: number },
    response: [200, "json", Array<Resource>],
  }>(async (ctx) => {
    // list
  }),

  POST<{
    json: ResourcePayload,
    response: [201, "json", Resource],
  }>(async (ctx) => {
    // create
  }),
]);`;

export default defineConfig({
  backend: {
    stack: "hono",
    base: "/api",
    templates: { "admin/**": resourceTemplate },
  },
});
```

Then create the route folders. Each new `index.ts` arrives with the right structure - typed handlers, declared `response`
(so the [fetch client is typed](/fetch/type-safety#without-a-response-the-result-is-unknown) and OpenAPI picks it up),
ready to adapt instead of retyped.

Pair it with a colocated `types.ts` per route folder and the skeleton stays honest:
the template references `./types`, and each route defines its own.

## Common Use Cases

```ts
backend: {
  stack: "hono",
  base: "/api",
  templates: {
    "admin/**": crudTemplate,        // consistent admin endpoints
    "webhooks/**": webhookTemplate,  // signature verification + 200 fast
    "internal/**": internalTemplate, // runtimeValidation: false, trusted callers
  },
}
```

---

---
url: /frontend/intro.md
description: >-
  Integrate KosmoJS directory-based routing with React, SolidJS, Vue, Svelte, or
  MDX. Automatic route configuration, type-safe navigation, and optimized lazy
  loading for modern frontend applications.
---

Every source folder runs one frontend framework - **React**, **SolidJS**, **Vue**, **Svelte** or **MDX** -
picked when you create the folder. Different folders can run different ones in the same project.

Whichever you choose, the shape of the work is the same: components under `pages/` become the routes,
navigation and data loading are typed end to end, and page code is split automatically.

Nothing about the framework itself changes -
you keep its router, its reactive model and its ecosystem, exactly as documented upstream.

## What's in the Folder

These are the files that make the folder an application.
Every one is a real source file you own: written once when the folder is created, never re-seeded behind your back.

```text
src/<folder>/
├── kosmo.config.ts       -> this folder's config (and its Vite config)
├── tsconfig.json         -> extends lib/front/tsconfig.json
├── index.html            -> Vite's HTML entry
├── app.tsx               -> global wrapper around EVERY route
├── router.ts             -> wires routes into the native router
│
├── entry/
│   ├── client.ts         -> mount vs hydrate, in the browser
│   └── server.ts         -> renderToString / renderToStream  (SSR only)
│
├── components/
│   └── Link.tsx          -> type-safe navigation component
│
└── pages/
    ├── 404.tsx           -> rendered for unmatched routes
    ├── index/
    │   └── index.tsx     -> the route  ->  /
    └── users/
        ├── layout.tsx    -> wraps everything under /users
        └── [id]/
            └── index.tsx -> the route  ->  /users/:id
```

### Foundation files

| File | What it is | When you touch it |
|---|---|---|
| `app.*` | The **global wrapper**, rendered around every route including `404` - the place for providers, auth gates, analytics, an app-wide error boundary. Not a layout: it has no folder scope, it simply wraps everything. | Providers, global chrome |
| `router.ts` | `routerFactory` - hands your `app` plus the derived routes to the framework's native router, returning `clientRouter()` for browser navigation and `serverRouter(url)` for SSR. | Rarely |
| `entry/client.*` | The browser entry, referenced from `index.html`. `renderFactory` picks `mount()` (fresh render) or `hydrate()` (SSR markup already present) automatically. | Rarely |
| `entry/server.*` | The SSR entry, exporting `renderToString` and - where the framework supports it - `renderToStream`. Only present when SSR is enabled. | Injecting SSR assets into `head` |
| `components/Link.*` | The typed [Link](/frontend/link-navigation) component: `to` takes a `[routeName, ...params]` tuple, so renaming a route directory becomes a compile error at every call site. | Styling it |
| `index.html` | Vite's HTML entry, loading `entry/client`. | Meta tags, fonts, the mount node |
| `tsconfig.json` | Extends the derived `lib/<folder>/tsconfig.json`, which carries JSX and path settings. Anything you set here wins. | [Relaxing strictness](/backend/type-safety) |
| `kosmo.config.ts` | The folder's [configuration](/essentials/config) - the `frontend`, `backend` and `validation` blocks, and any Vite option. | Turning on SSR, adding Vite plugins |

### Inside `pages/`

| File | What it is |
|---|---|
| `<route>/index.*` | **The route**. Its folder path becomes the URL. |
| `<route>/layout.*` | Wraps that folder and everything beneath it. Only works **inside a route folder**. [Details ›](/frontend/layouts) |
| `404.*` | The catch-all [error page](/frontend/error-pages) for unmatched URLs. |
| anything else | A colocated helper - never a route. |

### Extensions per framework

`router.ts` and `entry/*` are always `.ts`; everything else follows the framework:

| | React | SolidJS | Vue | Svelte | MDX |
|---|:---:|:---:|:---:|:---:|:---:|
| App file | `app.tsx` | `app.tsx` | `app.vue` | `app.svelte` | `app.mdx` |
| Page | `index.tsx` | `index.tsx` | `index.vue` | `index.svelte` | `index.mdx` / `.md` |
| Layout | `layout.tsx` | `layout.tsx` | `layout.vue` | `layout.svelte` | `layout.mdx` |
| Error page | `404.tsx` | `404.tsx` | `404.vue` | `404.svelte` | `404.mdx` |
| `Link` | `Link.tsx` | `Link.tsx` | `Link.vue` | `Link.svelte` | `Link.tsx` |
| Extra | – | – | – | – | `components/mdx.ts` (component map) |

A source folder runs exactly one framework and ignores the others' files - a Vue folder never picks up a stray `.tsx` page.
[Full matrix ›](/essentials/frameworks#frontends)

Derived code - the route table, fetch clients, validators - lives in `lib/`, is git-ignored,
and is not something you read to learn the project. [Why codegen ›](/essentials/why-codegen)

## TypeScript Configuration

Mixing frameworks across source folders requires per-folder TypeScript
configuration. Each framework has its own JSX import source requirement:

| Framework | `jsxImportSource` |
|-----------|-------------------|
| React | `"react"` |
| SolidJS | `"solid-js"` |
| Vue | `"vue"` *(only when using JSX)* |
| Svelte | n/a *(no JSX - compiled from `.svelte`)* |
| MDX | `"preact"` |

KosmoJS delegates JSX transformation to Vite, not TypeScript -
but differing `jsxImportSource` values cause type
conflicts when multiple frameworks coexist in the same project.

Solved by deriving a `tsconfig.json` specific to each source folder,
placed in the `lib/` directory for the source folder to extend:

```json [src/front/tsconfig.json]
{ "extends": "../../lib/front/tsconfig.json" }
```

Each config supplies the correct `jsxImportSource`, path mappings, and core settings.

## What Differs Between Frameworks

Routing, layouts, validation and the fetch clients behave identically everywhere.
Data loading, streaming support, SSG, TanStack Query and the exotic routing syntaxes do not -
those differences are collected in one table:

[Framework Support Matrix ›](/essentials/frameworks#frontends)

---

---
url: /frontend/application.md
description: >-
  Seeded foundation files for React, SolidJS, Vue, Svelte and MDX applications -
  root app component, AppProvider seam, router configuration and client entry
  point with SSR hydration support.
---

Creating a source folder seeds a small set of foundation files that wire up routing,
navigation, and application bootstrap.

The structure is consistent across frameworks:
a root app component, a router configuration, and a client entry point.

## Root Application Component

A minimal root component is seeded as your application shell.
Extend it with global layouts, error boundaries, authentication providers,
or other application-wide concerns.

The shell composes `AppProvider`, imported from `_/app`, around the routed tree.
`_/app` is a derived seam: a wrapper KosmoJS owns and can swap under the hood.

By default it is a pass-through (it renders its children unchanged),
so out of the box your app behaves exactly like a plain shell.

### Root Application Component - React

```tsx
// React: app.tsx
import { Outlet } from "react-router";
import { AppProvider } from "_/app";

export default function App() {
  return (
    <AppProvider>
      <Outlet />
    </AppProvider>
  );
}
```

### Root Application Component - Solid

```tsx
// Solid: app.tsx
import type { ParentComponent } from "solid-js";
import { AppProvider } from "_/app";

const app: ParentComponent = (props) => {
  return <AppProvider>{props.children}</AppProvider>;
};

export default app;
```

### Root Application Component - Vue

```vue
<!-- Vue: app.vue -->
<script setup lang="ts">
import { AppProvider } from "_/app";
</script>

<template>
  <AppProvider>
    <RouterView />
  </AppProvider>
</template>
```

### Root Application Component - Svelte

```svelte
<!-- Svelte: app.svelte -->
<script lang="ts">
  import type { Snippet } from "svelte";
  import { AppProvider } from "_/app";
  let { children }: { children: Snippet } = $props();
</script>

<AppProvider>
  {@render children()}
</AppProvider>
```

### Root Application Component - MDX

```mdx
// MDX: app.mdx
import { AppProvider } from "_/app";

<AppProvider>{props.children}</AppProvider>
```

### Why the AppProvider seam

Wrapping the shell in `AppProvider` costs nothing when it is a pass-through,
and it buys one thing: features that need to wrap the whole tree in a provider -
a query client, a theme, an auth context - can be enabled without you editing your code.

The pass-through `_/app` is swapped for one that installs the provider,
and the file that composes it is untouched because it already wires `AppProvider` unconditionally.

Toggling such a feature on or off never changes your code.
A plain shell would force you to add and remove the provider wiring by hand each time.

## Router Configuration

The `routerFactory` function in `router.ts` file connects your root app component
and derived routes to the framework's native router.
It accepts a callback receiving derived route definitions from KosmoJS.

The callback must return two functions:

* `clientRouter()` - browser-based routing for client-side navigation
* `serverRouter(url)` - server-side routing for SSR, receiving the requested URL

### Router Configuration - React

```tsx
// React: router.ts
import routerFactory, { createRouters } from "_/router";

import app from "./app";

export default routerFactory((routes) => {
  const { clientRouter, serverRouter } = createRouters(routes, { app });
  return {
    clientRouter() {
      return clientRouter()
    },
    serverRouter(url) {
      return serverRouter(url)
    },
  };
});
```

### Router Configuration - Solid

```tsx
// Solid: router.ts
import routerFactory, { createRouters } from "_/router";

import app from "./app";

export default routerFactory((routes) => {
  const { clientRouter, serverRouter } = createRouters(routes, { app });
  return {
    clientRouter() {
      return clientRouter()
    },
    serverRouter(url) {
      return serverRouter(url)
    },
  };
});
```

### Router Configuration - Vue

```ts
// Vue: router.ts
import routerFactory, { createRouters } from "_/router";
import { appProvider } from "_/app";

import app from "./app.vue";

export default routerFactory((routes) => {
  const { clientRouter, serverRouter } = createRouters(routes, {
    app,
    use: [[appProvider, undefined]],
  });
  return {
    clientRouter() {
      return clientRouter()
    },
    serverRouter(url) {
      return serverRouter(url)
    },
  };
});
```

### Router Configuration - Svelte

```svelte
<!-- Svelte: router.ts -->
import routerFactory, { createRouters } from "_/router";

import app from "./app.svelte";

export default routerFactory((routes) => {
  const { clientRouter, serverRouter } = createRouters(routes, { app });
  return {
    clientRouter() {
      return clientRouter()
    },
    serverRouter(url) {
      return serverRouter(url)
    },
  };
});
```

### Router Configuration - MDX

```tsx
// MDX: router.ts
import routerFactory, { createRouters } from "_/router";

import app from "./app.mdx";
import { components } from "./components/mdx"

export default routerFactory((routes) => {
  const { clientRouter, serverRouter } = createRouters(routes, { app, components });
  return {
    clientRouter() {
      return clientRouter()
    },
    serverRouter(url) {
      return serverRouter(url)
    },
  };
});
```

### Router Configuration (cont.)

The derived `routes` are always wrapped inside your `app` component,
establishing the layout hierarchy.

## Application Entry

The `entry/client.ts` file is your application's DOM rendering entry point,
referenced from `index.html`:

```html
<script type="module" src="./entry/client.ts"></script>
```

Vite begins from this HTML file, follows the import to `entry/client`, and
constructs the complete application dependency graph from there.

The `renderFactory` function orchestrates two rendering modes via a callback
that must return:

* `mount()` - mounts the application fresh in the browser
* `hydrate()` - hydrates pre-rendered server HTML for interactivity

On page load, `renderFactory` reads `__KOSMO_HYDRATION_BOOL__` flag to select the
correct method: `hydrate()` for SSR hydration, `mount()` for a fresh client-only mount.

### Application Entry - React

```tsx
// React: entry/client.ts
import renderFactory, {
  createRoutes,
  hydrate,
  mount,
} from "_/entry/client";

import routerFactory from "../router";

const routes = createRoutes({ withPreload: true });
const { clientRouter } = routerFactory(routes);

const root = document.getElementById("app");

if (root) {
  renderFactory(() => {
    return {
      hydrate() {
        return hydrate(() => clientRouter(), root);
      },
      mount() {
        return mount(() => clientRouter(), root);
      },
    };
  });
} else {
  console.error("❌ Root element not found!");
}
```

### Application Entry - Solid

```tsx
// Solid: entry/client.ts
import renderFactory, {
  createRoutes,
  hydrate,
  mount,
} from "_/entry/client";

import routerFactory from "../router";

const routes = createRoutes({ withPreload: true });
const { clientRouter } = routerFactory(routes);

const root = document.getElementById("app");

if (root) {
  renderFactory(() => {
    return {
      hydrate() {
        return hydrate(() => clientRouter(), root);
      },
      mount() {
        return mount(() => clientRouter(), root);
      },
    };
  });
} else {
  console.error("❌ Root element not found!");
}
```

### Application Entry - Vue

```ts
// Vue: entry/client.ts
import renderFactory, {
  createRoutes,
  hydrate,
  mount,
} from "_/entry/client";

import routerFactory from "../router";

const routes = createRoutes();
const { clientRouter } = routerFactory(routes);

const root = document.getElementById("app");

if (root) {
  renderFactory(() => {
    return {
      hydrate() {
        return hydrate(() => clientRouter(), root);
      },
      mount() {
        return mount(() => clientRouter(), root);
      },
    };
  });
} else {
  console.error("❌ Root element not found!");
}
```

### Application Entry - Svelte

```svelte
<!-- Svelte: entry/client.ts -->
import renderFactory, {
  createRoutes,
  hydrate,
  mount,
} from "_/entry/client";

import routerFactory from "../router";

const routes = createRoutes();
const { clientRouter } = routerFactory(routes);

const root = document.getElementById("app");

if (root) {
  renderFactory(() => {
    return {
      hydrate() {
        return hydrate(() => clientRouter(), root);
      },
      mount() {
        return mount(() => clientRouter(), root);
      },
    };
  });
} else {
  console.error("❌ Root element not found!");
}
```

### Application Entry - MDX

```tsx
// MDX: entry/client.ts
import renderFactory, {
  createRoutes,
  hydrate,
  mount,
} from "_/entry/client";

import routerFactory from "../router";

const routes = createRoutes();
const { clientRouter } = routerFactory(routes);

const root = document.getElementById("app");

if (root) {
  renderFactory(() => {
    return {
      hydrate() {
        return hydrate(() => clientRouter(), root);
      },
      mount() {
        return mount(() => clientRouter(), root);
      },
    };
  });
} else {
  console.error("❌ Root element not found!");
}
```

### Application Entry (cont.)

Under the hood:

* React uses `createRoot`/`hydrateRoot` from `react-dom/client`.
* SolidJS uses `render`/`hydrate` from `solid-js/web`.
* Vue constructs separate app instances via `createApp` and `createSSRApp`.
* Svelte uses `mount`/`hydrate` from `svelte`.
* MDX uses `render`/`hydrate` from `preact`.

The derived `hydrate` and `mount` are conveniences that wire the router to the
DOM the usual way - nothing more.

If you need custom mounting, ignore them and build the component yourself:
the entry only needs to render the router's component into `root`.

Read the derived `_/entry/client` source to see exactly what they do, then substitute your own.

---

---
url: /frontend/routing.md
description: >-
  Automatic route registration, lazy-loaded components, data loading
  integration, and nested layout patterns for React, SolidJS, Vue, Svelte and
  MDX applications.
---

Dev server continuously watches your `pages/` directory for new or updated pages.

You never wire routes by hand: as page components are created, updated or deleted,
a matching route configuration is written into `lib/` for the native router to consume.

## Same routing, both sides

Frontend routing follows the exact same directory-based pattern as API routing.
If you know how `api/` routes work, you already know how `pages/` routes work:

```
api/users/[id]/index.ts     ->  /api/users/:id   (backend handler)
pages/users/[id]/index.tsx  ->  /users/:id       (frontend component)
```

The parallel structure is intentional - an API endpoint and its corresponding
page are always one folder apart. The same parameter syntax applies to both:

| Syntax | Type | Example |
|---|---|---|
| `[id]` | Required | `pages/users/[id]/` -> `/users/123` |
| `{id}` | Optional | `pages/users/{id}/` -> `/users` or `/users/123` |
| `{...path}` | Splat | `pages/docs/{...path}/` -> `/docs/any/depth` |

Static routes always take priority over dynamic ones.
Optional parameters followed by static segments can cause ambiguity -
see [parameter details](/routing/params) for gotchas and solutions.

## Layouts

Layout files wrap groups of pages with shared UI - navigation, sidebars, auth shells -
at any level of the route hierarchy:

```
pages/
  dashboard/
    layout.tsx        - wraps all /dashboard/* pages
    settings/
      layout.tsx      - wraps all /dashboard/settings/* pages
      index.tsx
    index.tsx
```

Layouts stack outward-in and cannot be escaped by child routes.
[More on Layouts ›](/frontend/layouts)

## Routes

There is no central route tree for you to register or maintain -
no `routeTree.gen.ts` to import, no route config object to keep in sync.

Route definitions are written into `lib/<folder>/` and the framework's own router consumes them;
you reach them only through `createRoutes()` in your entry file, which the seeded boilerplate already wires up.

React, SolidJS and Vue each get a plain, **framework-native** route definition -
the same object you would have hand-written for that router.

Svelte and MDX have no third-party router, so KosmoJS supplies the matcher and emits its own `RawRoute` shape instead.

Because the output is native, everything your router documents keeps working:
lazy loading, nested layouts, navigation guards, `loader`/`preload`, error elements.
[Details ›](/routing/intro#native-routing-under-the-hood)

## Lazy Loading

All page components are lazy-loaded by default.

Route code is excluded from the initial JavaScript bundle and fetched on demand
when a user navigates to that path.

This keeps initial payloads small, accelerates application startup,
and ensures users download only the code for routes they actually visit.

## Data Loading on Navigation

Every framework integrates data fetching into the route lifecycle through a page-level `loader`/`preload` export.

**React** - when a page exports a `loader` function, React Router executes it at strategic moments:
initial page load, link hover, and navigation initiation.
Data is available before the component renders, eliminating loading spinners for route-level data.

**SolidJS** - when a page exports a `preload` function, SolidJS Router calls it on link hover and navigation intent.
The preload result is cached and reused by `createAsync` inside the component
(wrap the fetch in `query()` so both share one cache key), so no duplicate requests are made.

**Vue** - a page exports a `loader` (from a plain `<script>` block),
and the router runs it before the route renders via a navigation guard.
The component reads the result with `useLoaderData()` - no manual guards or `onMounted` needed.

**Svelte** - a page exports a `loader` (from its module `<script>` block);
the router runs it before render and the component reads it with `useLoaderData()`.

**MDX** - a page exports a `loader`; it runs before render and the page reads the result with the `useLoaderData()` hook.

Loader results are serialized during SSR and reused on hydration, so a request made on the server is not repeated on the client.

[Details ›](/frontend/data-preload)

---

---
url: /frontend/layouts.md
description: >-
  Compose shared UI at any level of the route hierarchy using layout files.
  Navigation, sidebars, auth shells, and data loading scoped to route subtrees
  for React, SolidJS, Vue, Svelte and MDX applications.
---

Layout files wrap groups of routes with shared UI - without duplicating
components across every page.

## Define a Layout

Create a `layout.tsx` (or `.vue` / `.svelte` / `.mdx`) in any folder under `pages/`,
and it automatically wraps every route in that folder and its subfolders.
Nest layouts by nesting folders.

```
pages/
  dashboard/
    layout.tsx         ← wraps all /dashboard/* pages
    settings/
      layout.tsx       ← wraps all /dashboard/settings/* pages
      profile/
        index.tsx      ← wrapped by both layouts
      index.tsx
    index.tsx
```

For `/dashboard/settings/profile`, the render order is:

```
app.tsx (global wrapper)
└── dashboard/layout.tsx
    └── dashboard/settings/layout.tsx
        └── dashboard/settings/profile/index.tsx
```

No configuration, no imports - the file system defines the hierarchy.

Child routes cannot escape parent layouts. Once a layout is established at a
folder level, all routes beneath it inherit it - keeping the UI hierarchy
predictable.

::: tip Looking for a layout that wraps every page?
That role belongs to the [app file](#global-layout-via-app-file),
not to a layout at the root of `pages/` - a root-level `pages/layout.*` is not picked up.
Layout files scope shared UI to a folder subtree; the app file wraps the whole app.
:::

## Layout File Naming

Only the lowercase form is recognized as a special file. `Layout.tsx`,
`LAYOUT.vue`, and other variations are treated as regular components.

| Framework | Recognized name |
|-----------|----------------|
| React / SolidJS | `layout.tsx` |
| Vue | `layout.vue` |
| Svelte | `layout.svelte` |
| MDX | `layout.mdx` |

Each source folder runs a single framework and ignores files belonging to
others: React/SolidJS folders ignore `.vue`/`.svelte` files, Vue folders ignore `.tsx`.

When you create a new layout file, KosmoJS seeds framework-appropriate
boilerplate immediately. Some editors may require a brief unfocus/refocus to
load the seeded content.

## Layout Implementation

Each framework renders child routes differently:

### Layout Implementation - React

```tsx
// React: layout.tsx
import { Outlet } from "react-router";

export default function Layout() {
  return (
    <div className="dashboard">
      <nav>...</nav>
      <main>
        <Outlet />
      </main>
      <footer>...</footer>
    </div>
  );
}
```

### Layout Implementation - Solid

```tsx
// Solid: layout.tsx
import type { ParentComponent } from "solid-js";

const Layout: ParentComponent = (props) => {
  return (
    <div class="dashboard">
      <nav>...</nav>
      <main>
        {props.children}
      </main>
      <footer>...</footer>
    </div>
  );
};

export default Layout;
```

### Layout Implementation - Vue

```vue
// Vue: layout.vue
<script setup lang="ts">
// layout-specific logic
</script>

<template>
  <div class="dashboard">
    <nav>...</nav>
    <main>
      <RouterView />
    </main>
    <footer>...</footer>
  </div>
</template>
```

### Layout Implementation - Svelte

```svelte
// Svelte: layout.svelte
<script lang="ts">
let { children } = $props();
</script>

<div class="dashboard">
  <nav>...</nav>
  <main>
    {@render children()}
  </main>
  <footer>...</footer>
</div>
```

### Layout Implementation - MDX

```mdx
// MDX: layout.mdx
<nav>
  <a href="/">Home</a>
  <a href="/docs">Docs</a>
</nav>

<main>
  {props.children}
</main>

<footer>
  Built with KosmoJS
</footer>
```

### Layout Implementation (cont.)

React renders child routes via `<Outlet />`. SolidJS and MDX use `props.children`,
Svelte renders `{@render children()}`, and Vue uses `<RouterView />`.

## Data Loading in Layouts

Layout data loading follows the same per-framework patterns as page components,
but how a layout's data stays distinct from its child page's differs:

* **React** scopes structurally - each route (layouts included) owns its `loader`,
  and `useLoaderData()` returns the calling route's data.
  No key; the route tree carries the identity.
* **SolidJS** keys by the `query()` cache string you supply (`"dashboard/data"` here),
  so the key lives in the `query()` wrapper, not the hook read.
* **Vue, Svelte, and MDX** share one per-route store keyed by route name, so the layout
  passes its path-qualified name to `useLoaderData` (a page passes nothing) -
  the hook can't tell which layout it runs in.

### Data Loading in Layouts - React

```tsx
// React: layout.tsx
import { Outlet, useLoaderData } from "react-router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["dashboard/data"];

export const loader = () => GET();

export default function Layout() {
  const data = useLoaderData();
  // ...
  return <Outlet />;
}
```

### Data Loading in Layouts - Solid

```tsx
// Solid: layout.tsx
import { Suspense, type ParentComponent } from "solid-js";
import { createAsync, query } from "@solidjs/router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["dashboard/data"];

// wrap in query() so preload and createAsync share one cache key
const getData = query(() => GET(), "dashboard/data");

export const preload = () => getData();

const Layout: ParentComponent = (props) => {
  const data = createAsync(() => getData());
  // ...
  return <Suspense>{props.children}</Suspense>;
};

export default Layout;
```

### Data Loading in Layouts - Vue

```vue
<!-- Vue: layout.vue -->
<script lang="ts">
import fetchClients from "_/fetch";

const { GET } = fetchClients["dashboard/data"];

// loader export lives in a plain <script> block
export const loader = () => GET();
</script>

<script setup lang="ts">
import { useLoaderData } from "_/use";

// a layout passes its path-qualified name to read its own data
const data = useLoaderData("dashboard/layout");
</script>

<template>
  ...
</template>
```

### Data Loading in Layouts - Svelte

```svelte
<!-- Svelte: layout.svelte -->
<script module lang="ts">
import fetchClients from "_/fetch";

const { GET } = fetchClients["dashboard/data"];

// loader export lives in the module <script> block
export const loader = () => GET();
</script>

<script lang="ts">
import { useLoaderData } from "_/use";

let { children } = $props();

// a layout passes its path-qualified name to read its own data
const data = useLoaderData("dashboard/layout");
</script>

<nav>{data.title}</nav>
<main>
  {@render children()}
</main>
```

### Data Loading in Layouts - MDX

```mdx
// MDX: layout.mdx
import fetchClients from "_/fetch";
import { useLoaderData } from "_/use";

const { GET } = fetchClients["dashboard/data"];

export const loader = () => GET();

export const Nav = () => {
  // a layout passes its path-qualified name to read its own data
  const data = useLoaderData("dashboard/layout");
  return <nav>{data.title}</nav>;
};

<Nav />
<main>
  {props.children}
</main>
```

### Data Loading in Layouts (cont.)

Loader/preload runs before the layout renders, so its data is available immediately
and shared across every child route without a duplicate fetch.

The read is a hook (`useLoaderData` / `createAsync`) rather than a prop -
`props` carries only `children`/`<Outlet />`.

Keeping a layout's data distinct from its page's is automatic in React (per-route)
and Solid (via the `query()` key); in Vue, Svelte, and MDX you pass the layout's
path-qualified name (e.g. `"dashboard/layout"` for `pages/dashboard/layout.*`) to the hook.

## Global Layout via app File

The `app.{tsx,vue,svelte,mdx}` at the source folder root wraps every route - the right
place for truly global concerns like authentication checks, analytics tracking
or error boundaries.

```txt
front/
├── app.tsx              ← wraps everything
└── pages/
    ├── dashboard/
    │   └── layout.tsx
    └── index/
        └── index.tsx
```

## Layout Hierarchy Example

For a deeply nested route like `/dashboard/settings/security`:

```txt
front/
├── app.tsx                        ← Level 1: global wrapper
└── pages/
    └── dashboard/
        ├── layout.tsx             ← Level 2: dashboard wrapper
        └── settings/
            ├── layout.tsx         ← Level 3: settings wrapper
            └── security/
                ├── layout.tsx     ← Level 4: security wrapper
                └── index.tsx      ← Level 5: page component
```

Renders as:

```
App
└── Dashboard Layout
    └── Settings Layout
        └── Security Layout
            └── Security Page
```

## Best Practices

* **Keep layouts focused.** Each layout handles concerns for its own scope - dashboard navigation in the dashboard layout, not global auth state.
* **Fetch shared data at the right level.** If multiple child routes need the same data, load it in their common parent layout rather than duplicating the fetch.
* **Use layouts for shared behavior.** Beyond UI structure, layouts suit shared logic: permission checks, analytics, or subscription state scoped to a route group.
* **Avoid deep nesting without purpose.** Three or four levels is reasonable. Beyond that, consider whether the hierarchy reflects genuine UI structure or accidental complexity.
* **Handle loading states explicitly.** Loader/preload data resolves before render, but a `createAsync` read that suspends (SolidJS) still wants a `<Suspense>` fallback scoped to the data component - see the data-preload guide.

## Common Pitfalls

* **Case sensitivity.** Only `layout.{tsx,vue,svelte,mdx}` are recognized as layout files.
* **Framework file isolation.** `.vue`/`.svelte` files in a React/SolidJS/MDX folder are ignored, and `.tsx/.mdx` files in a Vue/Svelte folder are ignored.
* **No layout opt-out.** Child routes always inherit parent layouts. Routes that shouldn't share a layout belong in a different directory branch.
* **Data loading uses hooks, not props.** All frameworks load layout data through a `loader`/`preload` export read with a hook (`useLoaderData`/`createAsync`).
  Keeping a layout's data separate from its page's is automatic in React (per-route) and Solid (via the `query()` key);
  in Vue, Svelte, and MDX the layout passes its path-qualified name to `useLoaderData` (a page passes nothing).

---

---
url: /frontend/data-preload.md
description: >-
  Prefetch route data before components render using React Router's loader
  pattern, SolidJS Router's query/preload, and Vue, Svelte and MDX loader
  exports. Type-safe data availability derived from API endpoint definitions.
---

Preloading ensures data is ready before a component renders, eliminating
loading spinners for route-level data and creating seamless navigation
experiences. Each framework has its own mechanism - all integrate naturally
with KosmoJS's fetch clients.

## API Endpoint

Start by creating an API endpoint that provides the data.
The same endpoint is used across every framework:

```ts [api/users/data/types.ts]
export type UserData = {
  users: Array<{ id: number; name: string }>;
};
```

### API Endpoint - Hono

```ts
// Hono: api/users/data/index.ts
import { defineRoute } from "_/api";
import type { UserData } from "./types";

export default defineRoute<"users/data">(({ GET }) => [
  GET<{ response: [200, "json", UserData] }>(async (ctx) => {
    return ctx.json(await fetchUserData());
  }),
]);
```

### API Endpoint - H3

```ts
// H3: api/users/data/index.ts
import { defineRoute } from "_/api";
import type { UserData } from "./types";

export default defineRoute<"users/data">(({ GET }) => [
  GET<{ response: [200, "json", UserData] }>(async (event) => {
    return await fetchUserData();
  }),
]);
```

### API Endpoint - Koa

```ts
// Koa: api/users/data/index.ts
import { defineRoute } from "_/api";
import type { UserData } from "./types";

export default defineRoute<"users/data">(({ GET }) => [
  GET<{ response: [200, "json", UserData] }>(async (ctx) => {
    ctx.body = await fetchUserData();
  }),
]);
```

### API Endpoint (cont.)

Declaring `response` is what gives the client a typed return value here -
and, on the client, an entry in the `ResponseT` map.
[Details ›](/fetch/type-safety#response-types)

## Page Integration

### Page Integration - React

```tsx
// React: pages/users/data/index.tsx
import { useLoaderData } from "react-router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/data"];

// Export the fetch function as loader -
// React Router calls it before the component renders
export const loader = () => GET();

export default function Page() {
  // useLoaderData retrieves the already-fetched result - no duplicate request
  const data = useLoaderData();

  return (
    <div>
      {data && <UserList users={data.users} />}
    </div>
  );
}
```

### Page Integration - Solid

```tsx
// Solid: pages/users/data/index.tsx
import { Suspense } from "solid-js";
import { createAsync, query } from "@solidjs/router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/data"];

// wrap the fetch in query() so preload and createAsync share one cache key -
// the raw client GET is not cached, so both must call the same query-wrapped fn
const getData = query(() => GET(), "users/data");

// SolidJS Router calls preload on link hover and navigation intent
export const preload = () => getData();

export default function Page() {
  // createAsync reads the same query cache the preload warmed - no duplicate request
  const data = createAsync(() => getData());

  // reading data() in JSX suspends while the value is pending (cold navigation),
  // so it needs a <Suspense> above it - see "Suspense Is Your Responsibility"
  return (
    <Suspense fallback={<Spinner />}>
      <UserList users={data()?.users} />
    </Suspense>
  );
}
```

### Page Integration - Vue

```vue
<!-- Vue: pages/users/data/index.vue -->
<script lang="ts">
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/data"];

// the loader is a module-level export, so it lives in a plain <script> block -
// <script setup> compiles to setup() and cannot hold ES exports
export const loader = () => GET();
</script>

<script setup lang="ts">
import { useLoaderData } from "_/use";

// the router runs the loader before the component renders; read its result here
const data = useLoaderData();
</script>

<template>
  <div>
    <UserList v-if="data" :users="data.users" />
  </div>
</template>
```

### Page Integration - Svelte

```svelte
<!-- Svelte: pages/users/data/index.svelte -->
<script module lang="ts">
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/data"];

// the loader lives in the module <script> block -
// the instance <script> can't hold ES exports
export const loader = () => GET();
</script>

<script lang="ts">
import { useLoaderData } from "_/use";

// the router runs the loader before the component renders; read its result here
const data = useLoaderData();
</script>

{#if data}
  <UserList users={data.users} />
{/if}
```

### Page Integration - MDX

```mdx
// MDX: pages/users/data/index.mdx
import fetchClients from "_/fetch";
import { useLoaderData } from "_/use";

export const { GET } = fetchClients["users/data"];

export const loader = () => GET();

export const Users = () => {
  const data = useLoaderData();
  return <UserList users={data.users} />;
};

# Users

<Users />
```

## How It Works

**React** - the `loader` export tells React Router what function to call
before rendering. `useLoaderData` retrieves the result that was already
fetched - no duplicate request. Type safety flows end-to-end: the fetch
client's `GET` is typed from your API definition, and `useLoaderData` is
parameterized with the matching response type.

**SolidJS** - the `preload` export tells SolidJS Router to call the function
on link hover and navigation intent. Dedup comes from `query()`: it caches by
the arguments passed to the wrapped function, so `preload` and `createAsync`
calling the same `getData()` hit one cache key and the fetch runs once. The
raw client `GET` is not itself cached, so wrapping it in `query()` is what makes
the preloaded result reusable - `createAsync(() => GET())` on the bare client
would fetch again.

**Vue** - a page exports a `loader` (in a plain `<script>` block, since
`<script setup>` cannot hold ES exports), and the router runs it before the
component renders. The component reads the result with `useLoaderData()` - no
`onMounted`, no manual `ref`, and the data is available synchronously at first
render, so it works under SSR without a re-fetch on hydration.

**Svelte** - identical shape to Vue and MDX: a page exports a `loader` from its
module `<script>` block, the router runs it before render, and the instance
`<script>` reads the result with `useLoaderData()`. KosmoJS uses only Svelte's
UI layer, not SvelteKit, so data loading is the loader, not SvelteKit's `load`.

**MDX** - export a `loader` and read its result with the `useLoaderData()`
hook; `props` stays entirely yours. It runs before the page renders, on both
server and client, through the same fetch client used elsewhere - so a request
made during SSR is replayed on hydration rather than firing twice.

## Suspense Is Your Responsibility

Async data reads need a `<Suspense>` boundary above them, and KosmoJS does
not provide one for you. The seeded `App` boilerplate renders its children
directly - it deliberately does not wrap the app in `<Suspense>`, because a
single app-wide boundary is an anti-pattern: any pending fetch anywhere
collapses the whole page to one fallback, and unrelated async work shares a
single loading state. Where the boundary goes is a design decision only you
can make, so KosmoJS leaves it to you.

This matters most for **SolidJS**. `createAsync` reports its pending state to
the nearest `<Suspense>` and propagates errors to the nearest
`<ErrorBoundary>`; with no boundary above it, the pending read has nowhere to
report and the component cannot render its resolved content. Wrap the data
component - or a sensible subtree around it - yourself:

```tsx [SolidJS]
import { Suspense } from "solid-js";

export default function Page() {
  const data = createAsync(() => getData());

  return (
    <Suspense fallback={<Spinner />}>
      <UserList users={data()?.users} />
    </Suspense>
  );
}
```

**React** - the `loader`/`useLoaderData` pattern shown above resolves before
render and does not suspend, so it needs no boundary. You only need
`<Suspense>` if you reach for `React.lazy` or a promise-throwing `use()` read.

**Vue** - the `loader`/`useLoaderData` pattern resolves before render and does
not suspend either, so it needs no boundary. A `<Suspense>` boundary is only
relevant if you reach for async `<script setup>` (a top-level `await`), which
turns the component async and wants a boundary above it.

**Svelte** - the `loader`/`useLoaderData` pattern resolves before render and
does not suspend, so it needs no boundary in the common case.

**MDX** - `loader`/`useLoaderData` resolves before render and does not suspend,
so it needs no boundary in the common case.

Wrapping the entire app in one boundary does work if you accept the tradeoff -
it is your call, not a default KosmoJS will make for you. The guidance is to
scope boundaries to the components or sections that actually fetch, so a
spinner in one area never blanks the rest of the page.

---

---
url: /frontend/hooks.md
description: >-
  Reference for the derived _/use module - useLoaderData, useParams, useRoute,
  useParamsEntries, useSearchParams and useFrontmatter - and which frameworks
  provide it.
---

`_/use` is a small derived module holding the hooks a page needs that its router doesn't already provide.

::: warning It does not exist for every framework
`_/use` is derived **only for Vue, Svelte and MDX folders**. React and SolidJS folders
have no `_/use` at all - React Router and Solid Router already cover this ground, so you
import from them instead.
An `import { ... } from "_/use"` in a React or SolidJS folder will not resolve.
:::

## What each framework provides

| | React | SolidJS | Vue | Svelte | MDX |
|---|:---:|:---:|:---:|:---:|:---:|
| `_/use` exists | ❌ | ❌ | ✅ | ✅ | ✅ |
| `useLoaderData` | – | – | ✅ | ✅ | ✅ |
| `useRoute` | – | – | – | ✅ | ✅ |
| `useParams` | – | – | – | ✅ | ✅ |
| `useParamsEntries` | – | – | – | ✅ | ✅ |
| `useSearchParams` | – | – | – | ✅ | ✅ |
| `useFrontmatter` | – | – | – | – | ✅ |

Where a cell is empty, use the framework's own equivalent:

| Need | React | SolidJS | Vue |
|---|---|---|---|
| loader data | `useLoaderData` from `react-router` | `createAsync` from `@solidjs/router` | `useLoaderData` from `_/use` |
| route params | `useParams` from `react-router` | `useParams` from `@solidjs/router` | `useRoute` from `vue-router` |
| search params | `useSearchParams` from `react-router` | `useSearchParams` from `@solidjs/router` | `useRoute().query` |

## `useLoaderData`

```ts
useLoaderData<T>(key?: string): T | undefined
```

Reads the result of the page's `loader` export, resolved before render.

### `useLoaderData` - Vue

```vue
<!-- Vue: pages/users/[id]/index.vue -->
<script setup lang="ts">
import { useLoaderData } from "_/use";
import type { ResponseT } from "_/fetch";

const user = useLoaderData<ResponseT["users/[id]"]["GET"]>();
</script>
```

### `useLoaderData` - Svelte

```svelte
<!-- Svelte: pages/users/[id]/index.svelte -->
<script lang="ts">
import { useLoaderData } from "_/use";
import type { ResponseT } from "_/fetch";

const user = useLoaderData<ResponseT["users/[id]"]["GET"]>();
</script>
```

### `useLoaderData` - MDX

```mdx
// MDX: pages/users/[id]/index.mdx
import { useLoaderData } from "_/use";

export const Profile = () => {
  // .mdx is not TypeScript - no type argument, the result is untyped
  const user = useLoaderData();
  return <p>{user?.name}</p>;
};

<Profile />
```

### `useLoaderData` (cont.)

`useLoaderData` exists only where `_/use` does - Vue, Svelte and MDX.
React reads loader data through `useLoaderData` from `react-router`, and
SolidJS through `createAsync` from `@solidjs/router`.

Two things to keep in mind:

* **It returns `T | undefined`.** The loader resolves before render in the normal case,
  but the type is honest about routes that declare no loader.
  Annotate the read and handle the empty case (`v-if="user"`, `{#if user}`) rather than asserting.
* **In a layout, pass the key.** Vue, Svelte and MDX share one per-route store keyed by route name,
  and the hook cannot tell which layout it is running in.
  A page passes nothing; a layout passes its path-qualified name:

```ts
const data = useLoaderData("dashboard/layout");   // pages/dashboard/layout.*
```

[Details ›](/frontend/layouts#data-loading-in-layouts)

## `useParams`

```ts
useParams<RouteName>(): ParamsMap[RouteName]
```

Svelte and MDX only.

On Svelte, pass the route name as a type argument and the params come back typed for that route -
required params as values, optional ones possibly `undefined`, a splat as an array or `undefined`.

An MDX page calls `useParams()` with no type argument and gets the same values untyped:

```svelte
<script lang="ts">
import { useParams } from "_/use";

const { slug } = useParams<"blog/[slug]">();
</script>
```

## `useRoute`

Returns the whole route context in one object - `name`, `params`, `paramsEntries`,
`searchParams`, `loaderData`, and on MDX also `frontmatter`.
Useful in a shared component (a breadcrumb, a title bar) that needs to know where it is without being handed props:

```tsx
import { useRoute } from "_/use";

export default function Breadcrumb() {
  const { name, params } = useRoute();
  // ...
}
```

## `useParamsEntries`

Returns `[keys, values]` - both arrays in the order the route declares its parameters,
which is exactly the order a fetch client expects:

```ts
const [keys, values] = useParamsEntries<"users/[id]/posts/[postId]">();
await fetchClients["users/[id]/posts/[postId]"].GET(values);
```

In MDX, call `useParamsEntries()` without the type argument -
the returned order is still correct, it is just untyped.

Prefer this over rebuilding an array from `useParams()`.
Object key order is insertion order in practice, but it is not tied to how the route declares its parameters -
`useParamsEntries` is correct by construction.
[Details ›](/frontend/mdx#loaders-with-route-parameters)

## `useSearchParams`

Returns the current query string as parsed search params, for reading `?page=2&sort=date` on the page side.

> This is *route-level* search state.
> Validating and typing query parameters is a separate concern handled on the API contract,
> through the `query` validation target and the fetch clients.
> [Details ›](/validation/payload#validation-targets)

## `useFrontmatter`

MDX only. Reads the current page's YAML frontmatter,
for dynamic head content or conditional rendering in a layout:

```mdx [MDX]
import { useFrontmatter } from "_/use";

export const Header = () => {
  const { title } = useFrontmatter();
  return title ? <h1>{title}</h1> : null;
};
```

[Details ›](/frontend/mdx#frontmatter-head-injection)

## Two Rules That Bite

**Hooks run during render, never at module scope.** A hook call in a module-level export runs on import,
before any component exists:

```mdx
export const params = useParams();   // ❌ runs on import, fails
export const P = () => useParams();  // ✅ runs during render
```

This is also why a `loader` cannot use hooks - it runs before the component tree exists.
It receives the resolved route object as its argument instead.
[Details ›](/frontend/mdx#loaders-with-route-parameters)

**On Svelte, read them during component initialisation.** The Svelte hooks read Svelte context,
so - like any `getContext()` call - they are only valid at the top level of a `<script>` block.
Calling one inside an event handler or a callback that runs later will not work:

```svelte
<script lang="ts">
import { useParams } from "_/use";

const { id } = useParams<"users/[id]">();   // ✅ top level

function onClick() {
  const p = useParams<"users/[id]">();      // ❌ too late, no context
}
</script>
```

---

---
url: /frontend/server-side-render.md
description: >-
  Add SSR capabilities to React, SolidJS, Vue, Svelte and MDX applications using
  KosmoJS SSR setup. String and stream rendering patterns, production builds,
  and deployment configurations for server-rendered applications.
---

Source folders default to client-side rendering with Vite's dev server and HMR.
SSR adds production-ready server rendering while keeping your development workflow unchanged.

## Adding SSR Support

SSR is automatically enabled if selected during source folder creation (or via `--ssr` flag in CLI mode).
To add it to an existing folder, flip `ssr` on in your source folder's `kosmo.config.ts`:

```ts [kosmo.config.ts]
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  frontend: {
    stack: "react",
    base: "/front",
    ssr: true, // [!code ++]
  },
});
```

:::details SSR runs in production builds only

`pnpm dev` is **always** Vite + HMR + client-side rendering, whether or not SSR enabled.

To see, test or debug anything server-rendered, use [kosmo preview](/dev-build-run/production-preview) -
it serves the production build and rebuilds on change:

```sh
pnpm preview front
```

This trips up people arriving from Next/Nuxt/TanStack Start, where dev mirrors prod rendering.
See [Debugging SSR](#preview) for the working loop.
:::

## Server Entry Point

`entry/server.ts` is seeded with a default implementation.
`renderFactory` accepts a callback returning an object with two required methods:

* `renderToString(url, SSROptions)` - renders the complete page, then returns it
  as a string.
* `renderToStream(url, SSROptions)` - renders the page as a `ReadableStream` for
  progressive flushing.

Both methods return the same `{ head, html }` shape - the only difference is that
`renderToString` resolves `html` to a string, while `renderToStream` resolves it
to a `ReadableStream`. Both renderers are imported from `_/entry/server`, and each
method returns rendered content the server assembles into the full response.

Which method runs for a given route is controlled by [renderMode](#selecting-the-render-mode) -
both are implemented, and the mode decides which one the server calls per route.

### Server Entry Point - React

```ts
// React: entry/server.ts
import renderFactory, {
  createRoutes,
  renderToStream,
  renderToString,
} from "_/entry/server";

import routerFactory from "../router";

const routes = createRoutes({ withPreload: true });
const { serverRouter } = routerFactory(routes);

export default renderFactory(() => {
  return {
    renderToString(url, { assets }) {
      return renderToString(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
    renderToStream(url, { assets }) {
      return renderToStream(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
  };
});
```

### Server Entry Point - Solid

```ts
// Solid: entry/server.ts
import renderFactory, {
  createRoutes,
  renderToStream,
  renderToString,
} from "_/entry/server";

import routerFactory from "../router";

const routes = createRoutes({ withPreload: true });
const { serverRouter } = routerFactory(routes);

export default renderFactory(() => {
  return {
    renderToString(url, { assets }) {
      return renderToString(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
    renderToStream(url, { assets }) {
      return renderToStream(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
  };
});
```

### Server Entry Point - Vue

```ts
// Vue: entry/server.ts
import renderFactory, {
  createRoutes,
  renderToStream,
  renderToString,
} from "_/entry/server";

import routerFactory from "../router";

const routes = createRoutes();
const { serverRouter } = routerFactory(routes);

export default renderFactory(() => {
  return {
    renderToString(url, { assets }) {
      return renderToString(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
    renderToStream(url, { assets }) {
      return renderToStream(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
  };
});
```

### Server Entry Point - Svelte

```ts
// Svelte: entry/server.ts
import renderFactory, {
  createRoutes,
  renderToString,
  // no renderToStream on Svelte folders
} from "_/entry/server";

import routerFactory from "../router";

const routes = createRoutes();
const { serverRouter } = routerFactory(routes);

export default renderFactory(() => {
  return {
    renderToString(url, { assets }) {
      return renderToString(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
  };
});
```

### Server Entry Point - MDX

```ts
// MDX: entry/server.ts
import renderFactory, {
  createRoutes,
  renderToString,
  // no renderToStream on MDX folders
} from "_/entry/server";

import routerFactory from "../router";

const routes = createRoutes();
const { serverRouter } = routerFactory(routes);

export default renderFactory(() => {
  return {
    renderToString(url, { assets }) {
      return renderToString(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
  };
});
```

### Server Entry Point (cont.)

The two methods are near-identical - `renderToString` and `renderToStream` share
imports, `head` construction, and the `{ head, html }` return. The only
difference is which renderer produces `html`:

* `renderToString` resolves `html` to a string.
* `renderToStream` resolves `html` to a `ReadableStream`.

Both are awaited. The server writes the opening HTML with `head` injected,
emits `html`, then writes the closing HTML - you return content,
and template assembly and the response are handled for you.

MDX and Svelte are the exceptions to implementing both methods: they provide only
`renderToString` and their folders do not expose the streaming render mode -
MDX because it renders static content, Svelte because its folder ships string rendering only.

## Render Factory Arguments

Both methods receive the same first two arguments - the URL and options.
Options is an object with following properties:

| Property | Description |
|----------|-------------|
| `template` | Client `index.html` from the Vite build, with \<!--app-html--> placeholder for SSR injection |
| `manifest` | Vite's `manifest.json` - the full dependency graph for client modules |
| `assets` | SSR-related assets, must be injected manually |

Each `assets` entry offers several ways to consume the same asset:

```ts
{
  kind: "js" | "css";
  tag: string;      // ready-to-use <script> / <link>, for direct injection
  content: string;  // raw contents, for inlining as <style> or inline <script>
  size: number;     // for Content-Length or preload hints
  path?: string;    // asset URL, for building a tag with your own attributes.
                    // Absent for content-only assets, which have no standalone URL
}
```

The seeded entry passes `tag` straight through, which is the right default.
Reach for the other fields when an asset should be treated differently -
inlining CSS to avoid a blocking request, say, while leaving scripts as tags:

```ts
renderToString(
  () => serverRouter(url),
  {
    headerTags: assets.map(({ kind, tag, content }) =>
      kind === "css" ? `<style>${content}</style>` : tag,
    ),
  },
);
```

Most renderers only need `assets` to build `head`. `template` and `manifest` are
available for advanced cases. The stream passed to `renderToStream` is a Hono
`StreamingApi` instance - an escape hatch for custom flushing; default renderers
resolve `html` to a `ReadableStream` and leave the writing to the server.

`renderToStream` receives a third argument, the stream, for custom flushing control.

Those are the arguments the server passes *in*. The renderers you call from inside each method take their own options -
`headerTags`, and the [onError hook](#onerror-hook) for reporting a render that failed.

## Stream Rendering

Streaming renders the page as a `ReadableStream` instead of a single string,
letting the server flush the shell early and improving Time-to-First-Byte (TTFB)
for large pages or long data-fetching chains.

No extra code is needed beyond the `renderToStream` method already shown in the
[Server Entry Point](#server-entry-point) examples - it mirrors `renderToString`,
differing only in the renderer it calls and the `ReadableStream` it resolves to.

`renderToStream` from `_/entry/server` returns a web-standard `ReadableStream` for every framework,
so streaming works the same on Node, Bun, and Deno.

Streaming a route is opt-in per route via [renderMode](#selecting-the-render-mode).
MDX and Svelte are the exceptions: they provide no `renderToStream`, and their folders do not expose the streaming mode.

## Selecting the Render Mode

Every route defaults to string rendering.

To stream instead, pass `renderMode` in the `ssr` options and match routes by glob pattern:

```ts [kosmo.config.ts]
frontend: {
  ssr: {
    renderMode: {
      "docs/**": "stream",
    },
  },
}
```

* `renderMode: "string"` (default) - render every route to a string.
* `renderMode: "stream"` - stream every route.
* `renderMode: { ... }` - per-route selection by glob pattern.

`docs/*` matches only routes directly under `docs`; `docs/**` matches routes at any depth. Unmatched routes fall back to `"string"`.

To invert the default - stream everything, then opt specific routes back into strings - order patterns from specific to general:

```ts [kosmo.config.ts]
frontend: {
  ssr: {
    renderMode: {
      "users/**": "string",
      "**": "stream",
    },
  },
}
```

When a route matches multiple patterns, the first match wins - so more specific
patterns come first. Streaming a route requires the folder's renderer to
implement `renderToStream`; MDX and Svelte folders do not accept the streaming mode.

## Fetch Errors and Recovery

Pages fetch data during server rendering through the same fetch client the browser uses,
dispatched in-process into the API app.
When a fetch fails mid-render, what happens next depends on the render mode.

### The CSR fallback - string-rendered routes recover automatically.

A string-rendered page is produced in full before a single byte leaves the server,
so a failed fetch aborts the render while the response is still untouched -
the server falls back to serving the client `index.html` verbatim.

The browser receives a clean CSR page: the client entry mounts from scratch,
fetching is retried in the browser, and any remaining failure surfaces through the error handling
the page already implements for client-side navigation.
No configuration is needed - string routes degrade to CSR on their own.

The same catch covers a **hard render failure**, not just a failed fetch: if the component tree throws while rendering,
the partial output is discarded and the client shell is served in its place.

Server-side error boundaries behave differently in every framework,
so the fallback deliberately hands the failure to the client,
where one set of boundaries handles it the way it always does.

#### What it looks like in production

The server logs the failure and the fallback that followed:

```txt
WARN: SSR failed, fallback to CSR
SSRFetchError: /api/users/123: 500 [ Internal Server Error ]
```

Nothing else announces it. The visitor still gets a working page, the status code is unchanged,
and nothing in the browser says the page was meant to be server-rendered.

So a route can quietly stop being server-rendered and stay that way until someone reads that line
or notices the missing markup in view-source.

Which is exactly why the renderers take an [onError](#onerror-hook) hook:
it turns that line into an event your monitoring can see.

Two practical habits follow:

* **When a page loses its SSR, look at the server side first.**
  An empty shell in production is usually a failing API call during render, not a frontend bug.
* **Do not treat the fallback as an error strategy.**
  It keeps a bad deploy serving, it does not make the failure acceptable - the underlying call is still broken for every visitor of that route.

At build time there is no visitor waiting, so [SSG](/frontend/static-site-generation#error-handling) does the opposite:
a route that cannot be rendered is never written as a shell,
and one failure is enough to make the build write nothing and fail.

### Streaming routes do not recover.

Streaming exists to flush the shell before rendering completes,
so by the time a fetch fails, the status line, headers, and opening HTML are already on the wire -
there is no response left to replace, and no server-side fallback is possible.

Routes that enable streaming must handle fetch errors manually, inside the page itself:

* catch errors in loaders or components and render an explicit error state.
* treat failure as a regular data state: a streamed page should be able to render something for every state its data can be in.
* lean on the framework's containment primitives
  * React contains the failure through the enclosing Suspense boundary:
    the stream survives, the server emits the suspense fallback, and the client retries the subtree,
    where an error boundary takes over (React never renders error boundary fallback HTML on the server);
  * Solid serializes resource errors into the stream and rethrows them during client hydration,
    where an `ErrorBoundary` catches them;
  * Vue has no streaming-side equivalent: `onErrorCaptured` can stop an error from propagating,
    which keeps the stream alive, but no fallback is rendered in that same server pass -
    the failed subtree is simply absent until the boundary takes over on the client.

What an unhandled mid-stream error produces is framework-specific -
a truncated document, a built-in fallback with client-side retry,
or an error deferred to hydration - none of which substitutes for explicit handling.

See [Error Boundaries](/frontend/error-boundaries) for how each framework's boundary behaves during server rendering.

MDX and Svelte folders are unaffected: they render strings only,
so every route recovers through the CSR fallback.

## onError hook

By default, rendering errors are logged to console.
To handle errors in a custom way, you can pass the `onError` method to `renderFactory`.

It is called with the error that ended the render, augmented with `url` property:

```ts [entry/server.ts]
export default renderFactory(() => {
  return {
    renderToString(url, { assets }) {
      return renderToString(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
    renderToStream(url, { assets }) {
      return renderToStream(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
    onError(error) { // [!code ++:3]
      reportToSentry(error, { url: error.url });
    },
  };
});
```

::: warning It reports, it does not repair
`onError` cannot change the response, patch the markup, or prevent what the render mode already does.
A string-rendered route still falls back to CSR; a streamed route's shell is still on the wire.
Returning a value from it changes nothing.
:::

The hook is the way to ship the error to your logger, to Sentry, to OpenTelemetry,
tagged with the URL and whatever request context you already carry.

What to do inside it:

* **Report, don't render.** Log, count, trace, page someone. Keep it cheap -
  it runs on the request path, in front of a visitor who is already waiting.
* **Never throw from it.** An `onError` that throws turns one failure into two,
  in the one place that was supposed to make failures observable.
* **Tag the render mode.** A string-rendered failure means one visitor got a CSR page;
  a streamed failure means one visitor got a broken document. They deserve different alert thresholds.

It fires in every environment that renders on the server - including [SSG](/frontend/static-site-generation#error-handling) pre-rendering,
where it runs inside the build, once per route that fails,
before the build reports them together and exits non-zero without writing any output.

## Preview

Because SSR never runs under `pnpm dev`, anything server-rendered is checked against the production build.
[kosmo preview](/dev-build-run/production-preview) does the build for you and rebuilds whenever you save:

```sh
pnpm preview front
```

Preview listens on `previewPort` (`4558` by default), so it runs alongside
`pnpm dev` rather than replacing it - keep both open and compare.

A few things that make debugging less painful:

* **Preview one folder.** `pnpm preview front` skips every other source folder.
* **Confirm you are actually seeing SSR.** View source (not the inspector):
  a server-rendered page arrives with real markup in `<div id="app">`.
  If it arrives empty, the render was skipped or it fell back to CSR.
* **Watch the server's stderr.** A failed fetch during a string render aborts that render
  and silently serves the CSR shell - the page still "works",
  so the terminal is where the failure shows up.
* **Isolate browser-only code.** `window`/`document` access during render is the most
  common SSR-only crash. Move it into an effect (`useEffect`/`onMounted`) or guard it
  with `typeof window !== "undefined"`.
* **Reach for a string render first.** If a route misbehaves only when streamed,
  drop it back to `"string"` in [renderMode](#selecting-the-render-mode)
  to find out whether the bug is in your render or in the streaming path.

## Production Build

### Production Build - npm

```sh
npm run build
```

### Production Build - pnpm

```sh
pnpm build
```

### Production Build - yarn

```sh
yarn build
```

### Production Build (cont.)

Produces an SSR bundle at `dist/<folder>/ssr/server.js`
and the `dist/<folder>/ssr/assets/` folder for hydration.

The SSR bundle also includes the API app. During server rendering the derived
fetch client dispatches to API routes in-process rather than over the network,
so data loading on the server has no HTTP round-trip - and the same bundle serves
API requests on its own port, no separate API process required.
[Isomorphic Fetch ›](/fetch/isomorphic-clients)

## Static Asset Handling

The SSR server serves static files itself, out of the box, from memory - two directories,
each one an allowlist of its own, nothing else in the bundle root is ever exposed:

* `dist/<folder>/ssr/assets/` - content-hashed by Vite, served at `<base>/assets/` with `Cache-Control: public, max-age=31536000, immutable`
* `dist/<folder>/ssr/public/` - a verbatim copy of the folder's `public/` directory (or whatever `publicDir` is set to in `kosmo.config.ts`),
  served at `<base>/` with `Cache-Control: no-cache`, since these names are stable and clients must revalidate

Static files take precedence over page routes, exactly as in the dev server.

There is no option to turn that off - and no need to: to keep static requests away from the SSR process entirely,
put a reverse proxy or CDN in front and let it serve both directories directly.

```nginx
location /assets/ {
  alias /srv/app/dist/front/ssr/assets/;
  expires 1y;
  add_header Cache-Control "public, immutable";
}

location / {
  root /srv/app/dist/front/ssr/public;
  try_files $uri @ssr;
}

location @ssr {
  proxy_pass http://ssr_backend;
}
```

## Runtime

The SSR server uses `node:http` which is natively supported by Node, Bun, and Deno.
Same bundle, same behavior, just pick your runtime:

### Runtime - Node

```sh
# Node
node dist/front/ssr/server.js -p 4556
```

### Runtime - Bun

```sh
# Bun
bun dist/front/ssr/server.js -p 4556
```

### Runtime - Deno

```sh
# Deno
deno run -A dist/front/ssr/server.js -p 4556
```

### Runtime (cont.)

Unix sockets are also supported across all three runtimes:

```sh
node dist/front/ssr/server.js -s /tmp/app.sock
```

## Production Deployment

Deploy behind a reverse proxy such as Nginx or Caddy:

```nginx
upstream ssr_backend {
  server 127.0.0.1:4556;
}

server {
  listen 80;
  server_name example.com;

  location / {
    proxy_pass http://ssr_backend;
  }
}
```

## Development Experience

SSR activates exclusively in production builds. During development:

* Run `pnpm dev` as usual
* Vite handles all requests with HMR
* Client-side rendering provides immediate feedback

When you need the server-rendered page, run [pnpm preview](/dev-build-run/production-preview) -
the production build, rebuilt on every save, on its own port so it sits alongside `pnpm dev`.

## Production Guidelines

* **Test locally before deploying.** Always verify your production bundle renders correctly before pushing to live servers -
  `pnpm preview` exists for exactly this.
* **Use streaming for large pages.** Applications with substantial HTML or complex data-fetching chains benefit from `renderToStream` -
  users see content faster as it arrives progressively.
* **Monitor process resources.** SSR keeps Node.js processes running continuously. Track memory consumption and implement error handling to prevent leaks.
* **Cache aggressively.** Place a CDN or cache layer in front of your SSR server for infrequently changing routes to reduce server load.
* **Implement error boundaries.** Add error boundaries throughout your application and handle errors in server entry points.
  Server errors shouldn't terminate the entire process.
* **Separate SSR and CSR concerns via source folders.** Rather than complex route-level SSR/CSR switching within a single folder,
  use KosmoJS's architectural strength: deploy an SSR source folder for marketing content and a CSR source folder for your application.
  Cleaner codebases, straightforward maintenance.

## Technical Considerations

* **Browser APIs unavailable during SSR.** Code executing server-side cannot access `window`, `document`, or browser-exclusive APIs.
* **Coordinate async data loading.** Suspense and resources work in SSR contexts,
  but complex async patterns require careful attention to ensure data is ready before rendering.
* **Bundle size still matters.** In SSR, initial bundle size affects server memory and startup time.
  The hydration bundle still downloads to clients, so optimization remains important.
* **Plan state serialization.** Applications with complex state require proper serialization for hydration.
  Each framework handles standard cases automatically, but custom stores or non-serializable data need special attention.

---

---
url: /frontend/static-site-generation.md
description: >-
  Pre-render React, SolidJS, Vue, Svelte and MDX pages to static HTML at build
  time with the KosmoJS SSG setup. Declaring staticParams for dynamic routes per
  framework, building in CI against production data, output layout, and
  deploying to a static host or CDN.
---

SSG renders pages to static HTML at build time,
for deploying to a CDN or any static host without a running server.

## Adding SSG Support

SSG is automatically enabled if selected during source folder creation (or via `--ssg` flag in CLI mode).
To add it to an existing folder, flip `ssg` on in your source folder's `kosmo.config.ts`:

```ts [kosmo.config.ts]
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  frontend: {
    stack: "react",
    base: "/front",
    ssr: true,
    ssg: true, // [!code ++]
  },
});
```

It works on source folders with a frontend and [SSR enabled](/frontend/server-side-render):
pages are rendered by the folder's own SSR server.

## Declaring `staticParams`

Static routes (no parameters) render automatically.
A dynamic route renders once per parameter set it declares through `staticParams`;
a dynamic route without `staticParams` is skipped - no file is written for it.

`staticParams` is a list of variants, each one positional in the route's parameter order.
A splat parameter takes an array of segments.

Where the declaration lives depends on how the framework exposes named exports from a page module:

### Declaring `staticParams` - React

```tsx
// React: pages/docs/[slug]/index.tsx
import { defineStaticParams } from "_/core";

export const staticParams = defineStaticParams<"docs/[slug]">([
  ["getting-started"],
  ["routing"],
  ["validation"],
]);

export default function DocsPage() { /* ... */ }
```

### Declaring `staticParams` - Solid

```tsx
// Solid: pages/docs/[slug]/index.tsx
import { defineStaticParams } from "_/core";

export const staticParams = defineStaticParams<"docs/[slug]">([
  ["getting-started"],
  ["routing"],
  ["validation"],
]);

export default function DocsPage() { /* ... */ }
```

### Declaring `staticParams` - Vue

```vue
<!-- Vue: pages/docs/[slug]/index.vue -->
<script lang="ts">
// a plain <script> block: <script setup> can not have named exports,
// and the two blocks coexist in one SFC
import { defineStaticParams } from "_/core";

export const staticParams = defineStaticParams<"docs/[slug]">([
  ["getting-started"],
  ["routing"],
]);
</script>

<script setup lang="ts">
/* ... */
</script>
```

### Declaring `staticParams` - Svelte

```svelte
<!-- Svelte: pages/docs/[slug]/index.svelte -->
<script module lang="ts">
// pages/docs/[slug]/index.svelte module-level script:
// its exports are the component module's named exports
import { defineStaticParams } from "_/core";

export const staticParams = defineStaticParams<"docs/[slug]">([
  ["getting-started"],
  ["routing"],
]);
</script>

<script lang="ts">
  /* ... */
</script>
```

### Declaring `staticParams` - MDX

```mdx
---
title: Documentation
staticParams:
  - [getting-started]
  - [routing]
---

{/* MDX declares staticParams in frontmatter, not as an export */}
```

### Declaring `staticParams` (cont.)

Values are stringified into the path, so numbers are fine: `[[1], [2], [42]]` renders `items/1`, `items/2`, `items/42`.

Data loading works as usual - the page's `loader` runs once per variant, with that variant's parameters,
against the API bundled into the SSR server.

::: tip React Fast Refresh
A non-component export in a React page file makes Fast Refresh fall back to a full reload for that file during development.
It is a development-only nuisance, the build is unaffected.
:::

## Where to Build

Pre-rendering runs your API.

The build starts a disposable SSR server, requests every declared path from it,
and each page's `loader` reaches the backend [in-process](/fetch/isomorphic-clients#ssg-runs-the-same-path-at-build-time) -
the same handlers, middleware and data sources that would answer a live request.

So the build machine needs the access production has: the database, the CMS, the upstream services your routes read.
This is why SSG belongs in a **CI workflow** rather than on a laptop.
A workflow that ships the sources to the production environment (or to a runner holding the same credentials and network reach),
installs there, and runs `build` there.

Pages are then rendered against exactly the data production would have served,
and the `ssg/` directory it produces is what you publish.

## Error Handling

Pre-rendering has no fallback.

If a page cannot be rendered - its loader's fetch fails, the API returns a non-2xx, a component throws -
the error is recorded and pre-rendering carries on through the remaining paths.

Then, at the end, one of two things happens:

* every page rendered, and the whole set is written.
* or at least one failed, and **nothing is written at all** - the collected errors reported.

Two properties come out of that, and both matter when you are waiting on a build:

* **One run names every broken route.** Aborting on the first failure would hide the other nine
  behind it, and finding them one rebuild at a time is how a ten-minute pipeline turns into an afternoon.
* **The output is all-or-nothing.** There is no half-written site to reason about,
  no question of which pages in `dist/` came from the run that failed, and nothing tempting to deploy from a red build.

This is deliberate, and it is the one place where SSG differs from SSR.
A live server that fails to render can [fall back to client rendering](/frontend/server-side-render#fetch-errors-and-recovery):
the visitor still gets a working page, the server logs the failure, and the next request may well succeed.

A static build has none of that. Whatever it writes is what visitors get, for as long as it stays published:

* **A shell page is indistinguishable from a good one.** It returns `200`, carries your layout, and
  contains nothing. No monitor flags it, and nobody notices until someone reads the page.
* **There is no server log to check afterwards.** The build was the only moment the failure was observable.
* **Static output gets cached hard** - a CDN, an immutable deploy, a proxy in front of it.
  A bad page can outlive the deploy that produced it.

So a broken page is never written - nor is any of its neighbours, until the whole set is good.
**A green build means every declared path rendered with real data**, which is exactly the guarantee
you want before publishing a directory of HTML.

The summary names every page that could not be rendered,
and the renderer's [onError hook](/frontend/server-side-render#onerror-hook) has already fired for each of them if you defined one -
the same hook that reports failures at serving time also reports them during the build.

The usual causes could be environmental rather than code:

* The build machine cannot reach the database or upstream service - see [Where to Build](#where-to-build).
* An environment variable the API needs is missing on the runner.
* A `staticParams` entry points at a record that no longer exists, so its loader gets a `404`.

Fix the causes and rebuild - or drop the stale entries from `staticParams` if those paths should no longer be pre-rendered.
Since one run reports all of them, a single pass over the summary is usually enough.

## Output

The build writes a complete static site to `dist/<folder>/ssg/`:

```txt
dist/front/ssg/
├── index.html
├── docs/
│   ├── getting-started/index.html
│   ├── routing/index.html
│   └── validation/index.html
├── assets/              -> hashed JS and CSS, the same set the SSR server serves
├── favicon.svg          -> public/ files, copied to the root
└── robots.txt
```

The tree is rooted at the folder's `base`, same as a Vite client build:
a folder with `base: "/admin"` produces `ssg/index.html`, `ssg/items/1/index.html` and so on,
and the HTML references `/admin/assets/...` - deploy the `ssg/` directory at `/admin/` on the host.

Nothing in the output depends on the `ssr/` or `client/` directories at serve time.

---

---
url: /frontend/error-boundaries.md
description: >-
  Catch rendering errors with each framework's native error boundary at the
  layout level. How boundaries behave during client rendering versus server-side
  rendering.
---

When a component throws while rendering, an error boundary catches it and shows fallback UI
instead of letting the failure tear down the surrounding tree.

KosmoJS doesn't ship its own boundary component or wrap your app in one -
each framework already has this mechanism, and you place it where it belongs:
in a [layout](/frontend/layouts), so it wraps the routes beneath it.

## Boundaries Live in a Layout

A `layout` file is the natural home for a boundary. It wraps every route in its
folder and subfolders, so one boundary there covers a whole section of the app
while leaving siblings elsewhere unaffected.

Wrap the layout's child slot - the same slot that renders the nested route - in your framework's boundary:

### Boundaries Live in a Layout - React

```tsx
// React: layout.tsx
import { Component, type ReactNode } from "react";
import { Outlet } from "react-router";

class Boundary extends Component<{ children: ReactNode }, { failed: boolean }> {
  state = { failed: false };
  static getDerivedStateFromError() {
    return { failed: true };
  }
  render() {
    return this.state.failed
      ? <div className="error">Something went wrong.</div>
      : this.props.children;
  }
}

export default function Layout() {
  return (
    <Boundary>
      <Outlet />
    </Boundary>
  );
}
```

### Boundaries Live in a Layout - Solid

```tsx
// Solid: layout.tsx
import type { ParentComponent } from "solid-js";
import { ErrorBoundary } from "solid-js";

const Layout: ParentComponent = (props) => {
  return (
    <ErrorBoundary fallback={(err) => <div class="error">Something went wrong.</div>}>
      {props.children}
    </ErrorBoundary>
  );
};

export default Layout;
```

### Boundaries Live in a Layout - Vue

```vue
// Vue: layout.vue
<script setup lang="ts">
import { ref, onErrorCaptured } from "vue";

const failed = ref(false);
onErrorCaptured(() => {
  failed.value = true;
  return false;
});
</script>

<template>
  <div v-if="failed" class="error">Something went wrong.</div>
  <RouterView v-else />
</template>
```

### Boundaries Live in a Layout - Svelte

```svelte
// Svelte: layout.svelte
<script lang="ts">
let { children } = $props();
</script>

<svelte:boundary>
  {@render children()}

  {#snippet failed(error, reset)}
    <div class="error">Something went wrong.</div>
  {/snippet}
</svelte:boundary>
```

### Boundaries Live in a Layout - MDX

```mdx
// MDX: layout.mdx
import { Boundary } from "~/components/Boundary";

<Boundary>
  {props.children}
</Boundary>
```

### Boundaries Live in a Layout (cont.)

MDX renders through a Preact host, so its boundary is a small Preact component
you import into the layout. Keep it in a `.tsx` file (MDX itself holds no TypeScript) using Preact's `useErrorBoundary` hook:

```tsx
// components/Boundary.tsx
import type { ComponentChildren } from "preact";
import { useErrorBoundary } from "preact/hooks";

export function Boundary({ children }: { children: ComponentChildren }) {
  const [error] = useErrorBoundary();
  if (error) return <div class="error">Something went wrong.</div>;
  return <>{children}</>;
}
```

Each of these uses the framework's own built-in primitive:

* React's class boundary with `getDerivedStateFromError`
* SolidJS's `<ErrorBoundary>`
* Vue's `onErrorCaptured`
* Svelte's `<svelte:boundary>`
* Preact's `useErrorBoundary` for MDX.

There's nothing KosmoJS-specific to learn; you use your framework's native boundary.

## Client Rendering and Server Rendering Differ

On the client, all five behave the way you expect: when a route below the
boundary throws during render, the boundary catches it and swaps in the fallback,
and the rest of the page keeps working. For a CSR folder this is the whole story.

Server-side rendering is where the behavior diverges,
and it's worth understanding before you rely on a boundary to rescue a bad server render.
The distinction that matters is *when* the error is thrown:

* An error thrown **asynchronously**, after a component's shell has already rendered -
  a lazy or suspended subtree that fails while resolving - is contained on the server: the render survives and produces HTML.
  Whether that HTML holds the boundary's fallback is framework-specific.
  Solid can emit it in the same pass; React never does - the server emits the enclosing *Suspense* fallback instead,
  the client retries the subtree, and the error boundary takes over there.
* An error thrown **synchronously**, at the top of a component's render on the initial pass (a "shell" error), is handled differently.
  This is the case a page that throws immediately in its render body falls into.

For a synchronous shell throw, only Solid renders the boundary's fallback on
the server. Its fine-grained model re-runs the boundary during the same render
and emits the fallback HTML, in both string and streaming output.

In React, Svelte, and MDX (Preact), the throw escapes the render call
rather than producing the boundary's fallback markup on the server.

In Vue, `onErrorCaptured` stops the error from propagating but the fallback branch isn't rendered in that same server pass.

In every one of those four cases the boundary still works normally once the
app hydrates on the client - the difference is confined to the initial server render.

This is upstream framework behavior, not a KosmoJS limitation, and it isn't something a config option changes.

In particular, the [renderMode](/frontend/server-side-render#selecting-the-render-mode)
setting (string versus stream) does not change the outcome for a synchronous shell throw -
streaming helps only with errors thrown after a shell has already flushed,
and streamed routes carry their own recovery caveats -
see [Fetch Errors and Recovery](/frontend/server-side-render#fetch-errors-and-recovery).

The practical consequence: a boundary is the right tool for recoverable
rendering errors in interactive subtrees, and it protects the client render in
every framework.

But don't lean on it to turn a hard server-render failure into a graceful server-rendered fallback -
a page that throws synchronously at the top of its render will not produce boundary fallback HTML on the server.

Handle those at the source: guard the code that can throw,
resolve data in a [loader or preload](/frontend/data-preload) so a failure surfaces through
the framework's data channel before render, and keep the boundary for the in-tree errors it catches well.

## Where This Fits

Boundaries handle errors thrown *while rendering*. They're one piece of a larger picture:

* Data-layer failures - a fetch client call that returns an HTTP error or throws on a network fault -
  surface through the mechanism you read the data with.
  See [Fetch Error Handling](/fetch/error-handling) for how a rejected request reaches a boundary in an event handler.
* Backend errors are separate again, centralized in `api/errors.ts`.
  See [Backend Error Handling](/backend/error-handling).
* A render error the server could not contain is **reported**, not caught, through the renderers'
  [onError](/frontend/server-side-render#onerror-hook) hook -
  the place to log or trace what a server-side boundary could not turn into fallback markup.
* A boundary is for render-time errors in a subtree;
  the root [app file](/frontend/layouts#global-layout-via-app-file) is where a truly
  global boundary would go if you want one that wraps everything.

---

---
url: /frontend/error-pages.md
description: >-
  The pages/404 component KosmoJS renders for unmatched routes - where it lives
  per framework, how it is registered as the router's catch-all, and how it
  behaves under CSR, SSR and SSG, including which HTTP status each one returns.
---

An **error page** is a full-page route rendered when a request can't be satisfied.

It is distinct from an [error boundary](/frontend/error-boundaries),
which catches a *rendering* error inside an otherwise-working page,
and from [api/errors.ts](/backend/error-handling), which handles failures on the API side.

Today there is exactly one error page: **404**. The `pages/<code>.*` shape is deliberate,
so more can join it later without changing the convention.

## The 404 page

Every frontend source folder gets one, at the root of `pages/`:

| Framework | File |
|---|---|
| React | `pages/404.tsx` |
| SolidJS | `pages/404.tsx` |
| Vue | `pages/404.vue` |
| Svelte | `pages/404.svelte` |
| MDX | `pages/404.mdx` |

It is **seeded once when the folder is created**, carrying a placeholder you are expected to replace.
From that point it is an ordinary source file: it is never re-seeded, never overwritten by a later boilerplate pass.

### The 404 page - React

```tsx
// React: pages/404.tsx
export default function NotFound() {
  return (
    <main>
      <h1>404 - Not Found</h1>
      <a href="/">Back home</a>
    </main>
  );
}
```

### The 404 page - Solid

```tsx
// Solid: pages/404.tsx
export default function NotFound() {
  return (
    <main>
      <h1>404 - Not Found</h1>
      <a href="/">Back home</a>
    </main>
  );
}
```

### The 404 page - Vue

```vue
<!-- Vue: pages/404.vue -->
<template>
  <main>
    <h1>404 - Not Found</h1>
    <a href="/">Back home</a>
  </main>
</template>
```

### The 404 page - Svelte

```svelte
<!-- Svelte: pages/404.svelte -->
<main>
  <h1>404 - Not Found</h1>
  <a href="/">Back home</a>
</main>
```

### The 404 page - MDX

```mdx
// MDX: pages/404.mdx

# 404 - Not Found

[Back home](/)
```

## How it is registered

It is appended to the folder's route list as the router's **catch-all (`path: "*"`), always last**,
so it matches only after every real route has failed to.

You never register it yourself and it never appears in the typed [Link](/frontend/link-navigation) route map -
there is no route name to link to.

Two consequences worth knowing:

* **The app file wraps it; layouts do not.** The catch-all is a top-level sibling of your routes,
  so [app.\*](/frontend/layouts#global-layout-via-app-file) - your global shell, nav, providers -
  still renders around it, but no `layout.*` does.
  A 404 under `/dashboard/anything` gets the app shell, not the dashboard layout.

* **It is lazy-loaded on the client** like any other page, and imported eagerly into the SSR bundle
  so the server can render it without a dynamic import.

## CSR, SSR and SSG

The same component is used in every mode - what differs is the **HTTP status** the visitor actually receives:

| Mode | Renders the page | HTTP status |
|---|---|---|
| CSR | ✅ client router matches the catch-all | whatever served the SPA fallback - normally **200** |
| SSR | ✅ rendered on the server | **404** |
| SSG | ❌ no `404.html` is emitted | your static host decides |

::: warning A client-rendered 404 is not a 404 to a crawler
Under CSR the host has already answered - typically `200 OK` with `index.html` - before your router decides nothing matched.
The visitor sees the right page; a crawler or an uptime check sees a success.
If correct status codes matter (SEO, monitoring), either enable [SSR](/frontend/server-side-render) for that folder,
or configure the fallback at the host/proxy level to return 404 for unknown paths.
:::

For [SSG](/frontend/static-site-generation) folders, nothing is pre-rendered for unmatched paths -
static hosts have their own not-found configuration (`404.html` on GitHub Pages and Netlify, `error_page` in Nginx, and so on).
Point it at whatever your host expects.

## What the 404 page is not

* **Not for API 404s.** A missing record behind `/api/users/[id]` is a backend concern:
  return a declared `[404, "json", ...]` response variant, or let it reach [api/errors.ts](/backend/error-handling).
  Requests under `backend.base` never render a page.
* **Not a render-error handler.** If a page throws while rendering,
  that is an [error boundary](/frontend/error-boundaries)'s job.
  The 404 page only ever renders because *routing* found nothing.
* **Not `not-found.tsx`.** There is no per-route not-found convention as in Next's App Router -
  one 404 page serves the whole source folder.
  Different folders have their own, which is usually the distinction you actually wanted.
  [Migration Tips ›](/essentials/migration-tips#loading-tsx-error-tsx-not-found-tsx)

## Triggering it deliberately

There is no `notFound()` helper. A route that exists but has nothing to show is a normal render decision -
branch in the component and render your own not-found UI, or redirect.
The catch-all page is reserved for URLs that match no route at all.

---

---
url: /frontend/tanstack-query.md
description: >-
  Integrate TanStack Query with KosmoJS. Build your app around the query
  provider using the client from _/query, prefetch in loaders for warm SSR with
  no duplicated payload, and read with useQuery. Per-framework guides for React,
  SolidJS, Vue and Svelte.
---

Enable TanStack Query when you create the source folder.
Interactive mode asks whether to enable it; for non-interactive runs pass `--tsq`:

```sh [CLI mode]
pnpm folder front --frontend react --tsq
```

Opting in sets `tanstack.query` in the `frontend` block.
You can also add it by hand later if you did not enable it at folder creation:

```ts [kosmo.config.ts]
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  frontend: {
    stack: "react",
    base: "/",
    ssr: true,
    tanstack: { query: true }, // [!code hl]
  },
});
```

Enabling it deploys a `_/query` runtime, wires a per-request `QueryClient` into
the SSR request scope, and swaps `_/app` for a provider that supplies the client (see below).

Everything else - your app, your reads - you write yourself, as plain TanStack Query.

`_/query` exports two things:

* `getQueryClient()` - resolves the active client. Per-request on the server
  (isolated per request, no cross-request cache leak), a singleton in the
  browser. Takes no arguments; import it in components and loaders and it always
  returns the right instance for the current environment.
* `createQueryClient(options?)` - builds one fresh, configured client and
  registers it as the active one. Call it once, at your app, and pass the result
  to the provider's `client` prop.

Beyond these two, KosmoJS does not wrap TanStack's SSR machinery in a
proprietary helper - warm SSR uses TanStack's own `dehydrate` and
`HydrationBoundary` directly, shown per framework in [SSR Warmup](#ssr-warmup-advanced) below.

MDX folders render static HTML with no client runtime, so TanStack Query is not
available there - fetch data with an MDX `loader` instead (see [MDX](/frontend/mdx)).

## Enabling and using it

Enabling the `tanstack.query` option wires everything for you.
The `_/query` runtime is deployed, `_/app` is swapped for a provider that supplies
the query client, and - on the server - each request gets its own client.

None of this touches your app code: the provider seam is part of the
derived foundation (see [Application Structure](/frontend/application)), and it is
composed the same way whether the option is on or off.
Toggling the option never asks you to edit, copy, or paste anything.

So there is no setup step here. Once the option is on, the only thing you write is
the read itself - `useQuery` in a component (shown per framework in [Basic Usage](#basic-usage)).

## Basic Usage

The simplest read: `useQuery` against a fetch client, no loader and no seeding.
This runs on the client - the query fetches after the component mounts.
It is the right starting point; reach for the loader (next section) only when you want the
data ready during SSR.

### Basic Usage - React

```tsx
// React: components/User.tsx
import { useQuery } from "@tanstack/react-query";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export default function User({ id }: { id: string }) {
  const { data, isPending } = useQuery({
    queryKey: ["users", id],
    queryFn: () => GET([id]),
  });

  if (isPending) return <div>Loading...</div>;
  return <div>{data.name}</div>;
}
```

### Basic Usage - Solid

```tsx
// Solid: components/User.tsx
import { Show } from "solid-js";
import { useQuery } from "@tanstack/solid-query";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export default function User(props: { id: string }) {
  // Solid takes a thunk so the options track reactively
  const query = useQuery(() => ({
    queryKey: ["users", props.id],
    queryFn: () => GET([props.id]),
  }));

  return (
    <Show when={!query.isPending} fallback={<div>Loading...</div>}>
      <div>{query.data?.name}</div>
    </Show>
  );
}
```

### Basic Usage - Vue

```vue
<!-- Vue: components/User.vue -->
<script setup lang="ts">
import { useQuery } from "@tanstack/vue-query";
import fetchClients from "_/fetch";

const { id } = defineProps<{ id: string }>();
const { GET } = fetchClients["users/[id]"];

const { data, isPending } = useQuery({
  queryKey: ["users", id],
  queryFn: () => GET([id]),
});
</script>

<template>
  <div v-if="isPending">Loading...</div>
  <div v-else>{{ data?.name }}</div>
</template>
```

### Basic Usage - Svelte

```svelte
<!-- Svelte: components/User.svelte -->
<script lang="ts">
  // Svelte uses createQuery (not useQuery) and takes a thunk
  import { createQuery } from "@tanstack/svelte-query";
  import fetchClients from "_/fetch";

  let { id }: { id: string } = $props();
  const { GET } = fetchClients["users/[id]"];

  const query = createQuery(() => ({
    queryKey: ["users", id],
    queryFn: () => GET([id]),
  }));
</script>

{#if query.isPending}
  <div>Loading...</div>
{:else}
  <div>{query.data?.name}</div>
{/if}
```

### Basic Usage (cont.)

The read hook is where the frameworks differ most:

* React and Vue take the options object directly
* Solid and Svelte take a thunk (`() => (...)`) so the options stay reactive
* Svelte's hook is `createQuery`, not `useQuery`
* Svelte Query v6 uses runes, so the result is read directly (`query.data`) with no `$` prefix.
* The `queryKey`/`queryFn` shape is the same everywhere.

## SSR Warmup (advanced)

Everything above works without any SSR wiring: `useQuery` fetches on the client
after mount. That is the seamless path, and for most pages it is enough.

If you want a page's data rendered on the server and hydrated warm on the client,
you wire it yourself with TanStack Query's own SSR primitives -
`dehydrate` on the server, `HydrationBoundary` on the client.

This is intentional: KosmoJS provides the client and gets out of the way,
so you use TanStack's documented, framework-native APIs directly.
The mechanism is the same across frameworks -
prefetch into the request client, `dehydrate` it, carry the snapshot to the client,
`hydrate` (or wrap in `HydrationBoundary`) - but the exact idiom is each adapter's own.
Follow your framework's official SSR guide:

* React - https://tanstack.com/query/latest/docs/framework/react/guides/ssr
* Solid - https://tanstack.com/query/latest/docs/framework/solid/guides/ssr
* Vue - https://tanstack.com/query/latest/docs/framework/vue/guides/ssr
* Svelte - https://tanstack.com/query/latest/docs/framework/svelte/ssr

The one KosmoJS-specific detail: get the request-scoped client from
`getQueryClient()` (import from `_/query`) in your loader,
so the client you prefetch into is the same one the render reads.

Use one shared query-options helper in both the loader and the component so the `queryKey` matches -
prefetch under one key and read under another and the cache misses, forcing a refetch.

Sketches per framework - see the official guides above for the full picture:

### SSR Warmup (advanced) - React

```tsx
// React: pages/users/[id]/index.tsx
// Prefetch in the loader, dehydrate, then wrap the page in HydrationBoundary.
// https://tanstack.com/query/latest/docs/framework/react/guides/ssr
import { dehydrate, HydrationBoundary, useQuery } from "@tanstack/react-query";
import { useLoaderData, useParams } from "react-router";
import { getQueryClient } from "_/query";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

const queryOptions = (id: string) => ({
  queryKey: ["users", id] as const,
  queryFn: () => GET([id]),
});

export const loader = async ({ params }: { params: { id: string } }) => {
  const client = getQueryClient();
  await client.prefetchQuery(queryOptions(params.id));
  return dehydrate(client);
};

function User() {
  const { id } = useParams() as { id: string };
  const { data } = useQuery(queryOptions(id));
  return <div>{data?.name}</div>;
}

export default function Page() {
  const state = useLoaderData();
  return (
    <HydrationBoundary state={state}>
      <User />
    </HydrationBoundary>
  );
}
```

### SSR Warmup (advanced) - Solid

```tsx
// Solid: pages/users/[id]/index.tsx
// Solid Query rehydrates through Solid's generateHydrationScript(),
// which the SSR entry already emits - so there is no HydrationBoundary to place.
// Prefetch into the request client and the cache crosses to the browser automatically.
// https://tanstack.com/query/latest/docs/framework/solid/guides/ssr
import { useQuery } from "@tanstack/solid-query";
import { useParams } from "@solidjs/router";
import { getQueryClient } from "_/query";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

const queryOptions = (id: string) => ({
  queryKey: ["users", id],
  queryFn: () => GET([id]),
});

export const preload = ({ params }: { params: { id: string } }) =>
  getQueryClient().prefetchQuery(queryOptions(params.id));

export default function Page() {
  // Solid folders read params through Solid Router's own hook
  const params = useParams();
  const query = useQuery(() => queryOptions(params.id));
  return <div>{query.data?.name}</div>;
}
```

### SSR Warmup (advanced) - Vue

```vue
<!-- Vue: pages/users/[id]/index.vue -->
<!-- Prefetch + dehydrate in the loader; hydrate the page's script setup.
     https://tanstack.com/query/latest/docs/framework/vue/guides/ssr -->
<script lang="ts">
import { dehydrate } from "@tanstack/vue-query";
import { getQueryClient } from "_/query";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export const queryOptions = (id: string) => ({
  queryKey: ["users", id],
  queryFn: () => GET([id]),
});

export const loader = async ({ params }: { params: { id: string } }) => {
  const client = getQueryClient();
  await client.prefetchQuery(queryOptions(params.id));
  return dehydrate(client);
};
</script>

<script setup lang="ts">
import { hydrate, useQuery } from "@tanstack/vue-query";
import { useRoute } from "vue-router";
import { getQueryClient } from "_/query";
import { useLoaderData } from "_/use";

hydrate(getQueryClient(), useLoaderData());

// Vue folders read params through Vue Router's own hook;
// `_/use` on Vue exports useLoaderData only
const route = useRoute();
const { data } = useQuery(queryOptions(route.params.id as string));
</script>

<template>
  <div>{{ data?.name }}</div>
</template>
```

### SSR Warmup (advanced) - Svelte

```svelte
<!-- Svelte: pages/users/[id]/index.svelte -->
<!-- Prefetch + dehydrate in the loader; wrap the page in HydrationBoundary.
     https://tanstack.com/query/latest/docs/framework/svelte/ssr -->
<script module lang="ts">
import { dehydrate } from "@tanstack/svelte-query";
import { getQueryClient } from "_/query";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export const queryOptions = (id: string) => ({
  queryKey: ["users", id],
  queryFn: () => GET([id]),
});

export const loader = async ({ params }: { params: { id: string } }) => {
  const client = getQueryClient();
  await client.prefetchQuery(queryOptions(params.id));
  return dehydrate(client);
};
</script>

<script lang="ts">
import { HydrationBoundary, createQuery, useQueryClient } from "@tanstack/svelte-query";
import { useParams, useLoaderData } from "_/use";

const params = useParams<"users/[id]">();
const query = createQuery(() => queryOptions(params.id));
</script>

<HydrationBoundary state={useLoaderData()} queryClient={useQueryClient()}>
  <div>{query.data?.name}</div>
</HydrationBoundary>
```

### SSR Warmup (advanced) (cont.)

`dehydrate` returns a snapshot of the request client's cache; import it from your
`@tanstack/{framework}-query` package.

On React, Vue and Svelte you carry that snapshot to the client
(via the loader data) and hand it to `HydrationBoundary` or `hydrate`,
which merges it into the client cache before components read.

Solid needs none of this - `generateHydrationScript()` carries the cache for you.

## Mutations and Invalidation

Mutations use the same client and need no KosmoJS-specific wiring.
`invalidateQueries` refetches affected queries in place - the thing a loader
alone cannot do without re-navigating.

### Mutations and Invalidation - React

```tsx
// React: components/RenameUser.tsx
import { useMutation, useQueryClient } from "@tanstack/react-query";
import fetchClients from "_/fetch";

const { POST } = fetchClients["users/[id]"];

export default function RenameUser({ id }: { id: string }) {
  const qc = useQueryClient();
  const rename = useMutation({
    mutationFn: (name: string) => POST([id], { name }),
    onSuccess: () => qc.invalidateQueries({ queryKey: ["users", id] }),
  });
  return <button onClick={() => rename.mutate("New Name")}>Rename</button>;
}
```

### Mutations and Invalidation - Solid

```tsx
// Solid: components/RenameUser.tsx
// Solid's hooks take a thunk, like useQuery above
import { useMutation, useQueryClient } from "@tanstack/solid-query";
import fetchClients from "_/fetch";

const { POST } = fetchClients["users/[id]"];

export default function RenameUser(props: { id: string }) {
  const qc = useQueryClient();
  const rename = useMutation(() => ({
    mutationFn: (name: string) => POST([props.id], { name }),
    onSuccess: () => qc.invalidateQueries({ queryKey: ["users", props.id] }),
  }));
  return <button onClick={() => rename.mutate("New Name")}>Rename</button>;
}
```

### Mutations and Invalidation - Vue

```vue
<!-- Vue: components/RenameUser.vue -->
<script setup lang="ts">
import { useMutation, useQueryClient } from "@tanstack/vue-query";
import fetchClients from "_/fetch";

const props = defineProps<{ id: string }>();

const { POST } = fetchClients["users/[id]"];

const qc = useQueryClient();
const rename = useMutation({
  mutationFn: (name: string) => POST([props.id], { name }),
  onSuccess: () => qc.invalidateQueries({ queryKey: ["users", props.id] }),
});
</script>

<template>
  <button @click="rename.mutate('New Name')">Rename</button>
</template>
```

### Mutations and Invalidation - Svelte

```svelte
<!-- Svelte: components/RenameUser.svelte -->
<script lang="ts">
  // Svelte uses createMutation (not useMutation) and takes a thunk
  import { createMutation, useQueryClient } from "@tanstack/svelte-query";
  import fetchClients from "_/fetch";

  let { id }: { id: string } = $props();

  const { POST } = fetchClients["users/[id]"];

  const qc = useQueryClient();
  const rename = createMutation(() => ({
    mutationFn: (name: string) => POST([id], { name }),
    onSuccess: () => qc.invalidateQueries({ queryKey: ["users", id] }),
  }));
</script>

<button onclick={() => rename.mutate("New Name")}>Rename</button>
```

### Mutations and Invalidation (cont.)

The shape is identical across frameworks - swap `useMutation`/`useQueryClient`
for the `@tanstack/{solid,vue,svelte}-query` equivalents. Mutations are
client-side, so SSR does not affect them.

## Configuring a custom client

By default the provider uses the client from `getQueryClient()`, which needs no configuration.

When you want custom defaults - a global `staleTime`, retry policy, and so on -
build the client once with `createQueryClient(options)` and the provider picks it up.

`createQueryClient` both builds the configured client and registers it as the active one,
so every later `getQueryClient()` returns that same instance.

`getQueryClient()` takes no options, so there is no way to pass options that silently get ignored.

Where you call it differs slightly by framework - it goes wherever your app is composed:

### Configuring a custom client - React

```tsx
// React: app.tsx - pass the configured client to the provider's `client` prop
import { AppProvider } from "_/app";
import { createQueryClient } from "_/query";
import { Outlet } from "react-router";

const client = createQueryClient({
  defaultOptions: { queries: { staleTime: 60_000 } },
});

export default function App() {
  return (
    <AppProvider client={client}>
      <Outlet />
    </AppProvider>
  );
}
```

### Configuring a custom client - Solid

```tsx
// Solid: app.tsx - pass the configured client to the provider's `client` prop
import { AppProvider } from "_/app";
import { createQueryClient } from "_/query";
import type { ParentComponent } from "solid-js";

const client = createQueryClient({
  defaultOptions: { queries: { staleTime: 60_000 } },
});

const app: ParentComponent = (props) => {
  return <AppProvider client={client}>{props.children}</AppProvider>;
};

export default app;
```

### Configuring a custom client - Vue

```vue
<!-- Vue: app.vue - call createQueryClient in <script setup>; the provider resolves it -->
<script setup lang="ts">
import { AppProvider } from "_/app";
import { createQueryClient } from "_/query";

createQueryClient({ defaultOptions: { queries: { staleTime: 60_000 } } });
</script>

<template>
  <AppProvider>
    <RouterView />
  </AppProvider>
</template>
```

### Configuring a custom client - Svelte

```svelte
<!-- Svelte: app.svelte - pass the configured client to the provider's `client` prop -->
<script lang="ts">
  import { AppProvider } from "_/app";
  import { createQueryClient } from "_/query";
  import type { Snippet } from "svelte";

  let { children }: { children: Snippet } = $props();

  const client = createQueryClient({
    defaultOptions: { queries: { staleTime: 60_000 } },
  });
</script>

<AppProvider {client}>
  {@render children()}
</AppProvider>
```

### Configuring a custom client (cont.)

The `client` prop is typed as the adapter's `QueryClient` and exists only when the
option is enabled - so `<AppProvider client={...}>` type-checks exactly where you
would write it. Omit it and the default client is used.

## Streaming

The warm-SSR path here is exact under string rendering (the default). Streaming
(`renderToStream`) needs the framework's streamed-hydration boundary to capture
queries that resolve mid-stream; until you move a route to streaming, string
mode gives correct, fully-warm SSR.

---

---
url: /frontend/link-navigation.md
description: >-
  Link component wrapping each framework's native router with compile-time route
  validation. Autocomplete navigation targets, parameter enforcement, and query
  string handling for React, SolidJS, Vue, Svelte and MDX.
---

The `Link` component wraps each framework's native router link with compile-time route validation.
It knows your complete route structure and parameters, delivering autocomplete and type checking throughout navigation code.

The component is available at `components/Link.{tsx,vue,svelte}` in your source folder.

## Usage

The API is consistent across all frameworks - a `to` prop accepting a
typed tuple, an optional `query` prop for search parameters, and standard
router props passed through:

### Usage - Menu.tsx

```tsx
// Menu.tsx
import Link from "~/components/Link";

export default function Menu() {
  return (
    <nav>
      {/* Navigate to a static route */}
      <Link to={["index"]}>Home</Link>

      {/* Navigate with a required parameter */}
      <Link to={["users/[id]", 123]}>User Profile</Link>

      {/* Navigate with a parameter and query string */}
      <Link to={["posts/[slug]", "hello-world"]} query={{ ref: "sidebar" }}>
        Blog Post
      </Link>
    </nav>
  );
}
```

### Usage - Menu.vue

```vue
<!-- Menu.vue -->
<script setup lang="ts">
import Link from "~/components/Link.vue";
</script>

<template>
  <nav>
    <!-- Navigate to a static route -->
    <Link :to="['index']">Home</Link>

    <!-- Navigate with a required parameter -->
    <Link :to="['users/[id]', 123]">User Profile</Link>

    <!-- Navigate with a parameter and query string -->
    <Link :to="['posts/[slug]', 'hello-world']" :query="{ ref: 'sidebar' }">
      Blog Post
    </Link>
  </nav>
</template>
```

### Usage - Menu.svelte

```svelte
<!-- Menu.svelte -->
<script lang="ts">
import Link from "~/components/Link.svelte";
</script>

<nav>
  <!-- Navigate to a static route -->
  <Link to={["index"]}>Home</Link>

  <!-- Navigate with a required parameter -->
  <Link to={["users/[id]", 123]}>User Profile</Link>

  <!-- Navigate with a parameter and query string -->
  <Link to={["posts/[slug]", "hello-world"]} query={{ ref: "sidebar" }}>
    Blog Post
  </Link>
</nav>
```

## LinkProps Type

The `to` prop is typed as `LinkProps` - a discriminated union derived from
your route structure:

```ts
export type LinkProps =
  | ["index"]
  | ["users/[id]", id: string | number]
  | ["posts/[slug]", slug: string]
  // ... all other routes
```

Typing the first array element triggers TypeScript's IntelliSense with valid
route suggestions. Selecting a parameterized route requires providing those
parameters as subsequent array elements - the type system enforces this.

Renaming a route directory produces TypeScript errors at every `Link`
referencing the old name, turning refactors into an automated checklist.

---

---
url: /frontend/custom-templates.md
description: >-
  Override default seeded page components for specific routes using glob pattern
  matching. Seed specialized boilerplate for landing pages, admin dashboards,
  marketing sections etc.
---

Every frontend framework supports template overrides for specific routes through pattern-based matching.
Useful for standardizing structure across landing pages, admin tools, or any section requiring a consistent starting point.

Templates seed page `index` files - `pages/**/index.*` - and nothing else.
Every other seeded file gets the built-in minimal boilerplate to start from.

## Configuration

Pass custom templates through the `frontend` block in your source folder's `kosmo.config.ts`:

```ts [kosmo.config.ts]
import { defineConfig } from "@kosmojs/dev";

// [!code ++:8]
const landingTemplate = `
export default function Page() {
  return (
    <div class="landing-page">
      <h1>Welcome</h1>
    </div>
  );
}`;

export default defineConfig({
  frontend: {
    stack: "react",
    base: "/front",
    templates: { // [!code ++:4]
      "landing/*": landingTemplate,
      "marketing/**": landingTemplate,
    },
  },
});
```

Now every new route under `landing/` and `marketing/` will start with your template.

> **Templates only fill blank files.**
> Boilerplate is written into a file **only when that file is empty**.
> It never overwrites work you have already done - which is also why changing a template does not retroactively rewrite existing pages.
> To re-seed one, empty the file and it will be filled again.

## Pattern Syntax

Templates use glob-style patterns to match routes:

### Single-Depth Wildcard (`*`)

Matches routes at exactly one nesting level:

```ts
{ "landing/*": template }
```

**Matches:** `landing/home`, `landing/about`, `landing/[slug]`

**Excludes:** `landing/features/new` (too deep), `landing` (too shallow)

### Multi-Depth Wildcard (`**`)

Matches routes at any nesting depth:

```ts
{ "marketing/**": template }
```

**Matches:** `marketing/campaigns/summer`, `marketing/promo/2024/special`, `marketing/[id]/details`

### Exact Match

Targets a single specific route:

```ts
{ "products/list": template }
```

## Resolution Priority

When multiple patterns match, the first matching pattern wins - in the order the keys are
written, so order them most specific first:

```ts
templates: {
  "landing/home": homeTemplate,   // highest specificity
  "landing/*": landingTemplate,   // medium specificity
  "**": fallbackTemplate,         // lowest specificity
}
```

::: warning Numeric-looking patterns jump the queue
JavaScript objects order integer-like keys first, regardless of where you wrote them - so
a pattern such as `"2024/**"` is hoisted to the front and matches before anything above
it. Prefix it with `./` to keep your written order: `"./2024/**"`.
The `./` is stripped before matching.

The same applies to [renderMode](/frontend/server-side-render#selecting-the-render-mode), which uses the same resolver.
:::

## Parameter Compatibility

Route parameters are escaped before matching, so `[id]`, `{id}` and `{...path}` mean
themselves rather than glob syntax:

```ts
{
  "users/[id]": userTemplate,           // required parameter
  "products/{category}": productTemplate, // optional parameter
  "docs/{...path}": docsTemplate,        // splat parameter
  "shop/[category]/{sub}": shopTemplate, // combined
}
```

## Template Format

Templates are written to disk as the page component file.
A template can be either a **plain string**, or a **function** receiving the resolved route and returning the string -
useful when the output depends on the route itself:

```ts
templates: {
  // a plain string
  "landing/*": landingTemplate,

  // or a function of the route
  "admin/**": (route) => `
export default function Page() {
  return <h1>${route.name}</h1>;
}`,
}
```

Each framework has its own component structure:

### Template Format - React

```ts
// React: kosmo.config.ts
const customTemplate = `
import { useParams } from "react-router";

export default function Page() {
  const params = useParams();

  return (
    <div>
      <h1>Custom Template</h1>
      <p>Route params: {JSON.stringify(params)}</p>
    </div>
  );
}
`;
```

### Template Format - Solid

```ts
// Solid: kosmo.config.ts
const customTemplate = `
import { useParams } from "@solidjs/router";

export default function Page() {
  const params = useParams();

  return (
    <div>
      <h1>Custom Template</h1>
      <p>Route params: {JSON.stringify(params)}</p>
    </div>
  );
}
`;
```

### Template Format - Vue

```ts
// Vue: kosmo.config.ts
const customTemplate = `
<template>
  <div>
    <h1>Custom Template</h1>
    <p>Route params: {{ JSON.stringify(route.params) }}</p>
  </div>
</template>

<script setup lang="ts">
import { useRoute } from "vue-router";
const route = useRoute();
</script>
`;
```

### Template Format - Svelte

```ts
// Svelte: kosmo.config.ts
const customTemplate = `
<script lang="ts">
import { useParams } from "_/use";
const params = useParams();
</script>

<div>
  <h1>Custom Template</h1>
  <p>Route params: {JSON.stringify(params)}</p>
</div>
`;
```

### Template Format - MDX

```mdx
// MDX: kosmo.config.ts
import { useParams } from "_/use";

# Custom Template

Route params: {JSON.stringify(useParams())}
```

### Template Format (cont.)

> Templates use Handlebars syntax for any dynamic content injected during seeding.
> Avoid raw Vue interpolation {{"{{"}}}} inside template strings -
> wrap in quotes or escape as needed to prevent accidental Handlebars evaluation.

## Common Use Cases

### Landing & Marketing Pages

```ts
frontend: {
  stack: "react",
  base: "/front",
  templates: {
    "landing/**": landingTemplate,
    "marketing/**": marketingTemplate,
    "promo/**": promoTemplate,
  },
}
```

### Admin Interfaces

```ts
frontend: {
  stack: "react",
  base: "/front",
  templates: {
    "admin/**": adminTemplate,
  },
}
```

## Default Template Override

Routes without a matching pattern use the built-in default, which
displays the route name as a placeholder. Replace it globally with:

```ts
templates: {
  "**": myDefaultTemplate,
}
```

---

---
url: /frontend/mdx.md
description: >-
  Create content-focused source folders with MDX - static HTML rendering with
  Preact, nested layouts, frontmatter-driven head injection, typed Link
  component.
---

MDX source folders are purpose-built for content: documentation, blogs,
marketing pages, and any site where prose matters more than interactivity.

Pages are authored in MDX (Markdown with JSX), rendered to static HTML on the server with Preact,
and delivered with minimal client-side JavaScript by default.

## Enabling MDX

MDX is enabled automatically when you create a source folder and select MDX as the framework.
To add it to an existing folder:

```ts [kosmo.config.ts]
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  frontend: {
    stack: "mdx",
    base: "/docs",
    ssr: true,
    ssg: true,
  },
});
```

## Writing Pages

Pages are `.mdx` or `.md` files in your `pages/` directory.
Standard markdown syntax works alongside JSX components:

```mdx [pages/blog/index.mdx]
---
title: Blog
description: Latest posts and updates.
---

import Alert from "./Alert.tsx"

# Welcome to the Blog

Regular markdown works as expected - **bold**, *italic*, `code`,
[links](/about), and everything else.

<Alert type="info">
  JSX components work inline with markdown content.
</Alert>

## Recent Posts

- First post about KosmoJS
- Getting started with MDX
```

Frontmatter is defined in YAML between `---` fences.
It drives `<head>` injection and is accessible in pages and layouts via
`useFrontmatter()` (or `useRoute().frontmatter`).

## Using Components

Import Preact components directly into MDX files. TypeScript, props, hooks -
everything works in the `.tsx` file. The MDX file stays focused on content:

### Using Components - pages/blog/Alert.tsx

```tsx
// pages/blog/Alert.tsx
import type { JSX } from "preact";

export default function Alert(props: {
  type: "info" | "warning" | "error";
  children: JSX.Element;
}) {
  return (
    <div class={`alert alert-${props.type}`}>
      {props.children}
    </div>
  );
}
```

### Using Components - pages/blog/index.mdx

```mdx
// pages/blog/index.mdx
import Alert from "./Alert.tsx"

<Alert type="warning">
  Keep TypeScript in `.tsx` files - MDX only supports plain JavaScript.
</Alert>
```

### Global Component Overrides

Every markdown element (`# heading`, `` `code` ``, `[link](url)`) compiles to
a JSX call. Override any of them globally via the component map in
`components/mdx.ts`:

```tsx [components/mdx.ts]
import Link from "./Link";

export const components = {
  Link,

  // custom heading with anchor links
  h1: (props) => (
    <h1 id={props.children?.toString().toLowerCase().replace(/\s+/g, "-")}>
      {props.children}
    </h1>
  ),

  // syntax-highlighted code blocks
  pre: (props) => <pre class="code-block" {...props} />,
};
```

These overrides apply to all MDX pages via the `MDXProvider`.
Individual pages can still import and use additional components directly.

## Layouts

Layouts work identically to other frameworks -
a `layout.mdx` file wraps all pages and nested layouts within its folder:

```txt
pages/
├── index/
│   └── index.mdx         ← wrapped by root layout
├── docs/
│   ├── layout.mdx        ← wraps all docs/* pages
│   ├── links/
│   │   └── index.mdx     ← wrapped by root + docs layout
│   └── guide/
│       ├── layout.mdx    ← wraps all docs/guide/* pages
│       └── setup/
│           └── index.mdx ← wrapped by root + docs + guide layout
```

For `/docs/guide/setup` the render order is:

```
app.mdx (root layout)
└── pages/docs/layout.mdx
    └── pages/docs/guide/layout.mdx
        └── pages/docs/guide/setup/index.mdx
```

### Writing Layouts

Layouts receive the wrapped content as `props.children`. Everything else -
the page's frontmatter, loader data - is read with hooks, so `props` carries
only what a layout composes around:

```mdx [pages/docs/layout.mdx]
<nav>
  <a href="/">Home</a>
  <a href="/docs">Docs</a>
</nav>

<main>
  {props.children}
</main>

<footer>
  Built with KosmoJS
</footer>
```

Access the page's frontmatter with `useFrontmatter()` for dynamic head content
or conditional rendering:

```mdx [pages/layout.mdx]
import { useFrontmatter } from "_/use";

export const Header = () => {
  const frontmatter = useFrontmatter();
  return frontmatter.title ? (
    <header>
      <h1>{frontmatter.title}</h1>
    </header>
  ) : null;
};

<div class="page-wrapper">
  <Header />
  {props.children}
</div>
```

Layouts must be `.mdx` files - `.md` files cannot render `{props.children}`.

### Global Layout via app.mdx

`app.mdx` at the source folder root wraps every page - the right place
for truly global concerns like site-wide navigation, footer, or
analytics scripts:

```txt
src/content/
├── app.mdx              ← wraps everything
└── pages/
    ├── layout.mdx
    └── index/
        └── index.mdx
```

## Route Parameters

MDX pages support the same parameter syntax as other source folders:

```txt
pages/
  blog/
    post/
      [slug]/
        index.mdx        -> /blog/post/:slug
    {category}/
      index.mdx          -> /blog/:category (optional)
      {tag}/
        index.mdx        -> /blog/:category/:tag (both optional)
```

Access parameters inside a component using `useParams()` from `_/use`.
`.mdx` is not TypeScript, so it takes no type argument and the params come back untyped -
move anything that needs the typed form into a `.tsx` component and import it:

```mdx [pages/blog/post/[slug]/index.mdx]
import { useParams } from "_/use";

export const Post = () => {
  const { slug } = useParams();
  return <p>Reading: {slug}</p>;
};

# Blog post

<Post />
```

Optional parameters come back possibly-undefined,
and a splat parameter comes back as an array of segments or undefined:

```mdx [pages/blog/{category}/{tag}/index.mdx]
import { useParams } from "_/use";

export const Filters = () => {
  const { category, tag } = useParams();
  return <p>{category ?? "all"} / {tag ?? "all"}</p>;
};

<Filters />
```

Note the call sits **inside a component**, not at module scope - see the warning below.

`useRoute()` provides the full route context including name, params, frontmatter, and loader data:

```tsx
import { useRoute } from "_/use";

export default function Breadcrumb() {
  const { name, params, frontmatter } = useRoute();
  return <nav>...</nav>;
}
```

> **Important:** hooks must be called inside a component's render function,
> not at module scope. `export const params = useParams()` in an MDX file
> runs on import and will fail.

## Data Fetching

Pages can fetch data during render via a `loader` export - a function that
runs before the page is rendered, on both the server and the client.
It receives the resolved route as first argument, and its return value is read
inside the page with the `useLoaderData()` hook - `props` stays entirely yours.

```mdx [pages/users/index.mdx]
import f from "_/fetch";
import { useLoaderData } from "_/use";

export const loader = f["users"].GET;

export const Message = () => {
  const data = useLoaderData();
  return <p>The message is: {data.msg}</p>;
};

# Welcome

<Message />
```

`loader` fetches through the same client used elsewhere in the project,
so a request made during SSR is captured and replayed on hydration instead of firing twice -
no extra wiring needed on the page.

### Loaders with Route Parameters

`loader` runs before the page tree exists, so it can't use `useParams()`/`useRoute()` -
those are hooks, and hooks only work while Preact is actually
rendering a component. Instead, `loader` receives the resolved route object
directly as first argument:

```ts
// the object passed to `loader` - a subset of the route context,
// without frontmatter or loaderData (which aren't resolved yet at loader time)
type LoaderRoute = {
  name: string;
  params: Record<string, string | Array<string>>;
  paramsEntries: [keys: Array<string>, values: Array<unknown>];
};
```

`paramsEntries` is a `[keys, values]` tuple, both in the same order the route
declares its parameters - the same order `GET` expect:

```mdx [pages/blog/[slug]/index.mdx]
import f from "_/fetch";
import { useLoaderData } from "_/use";

export const { GET } = f["blog/[slug]"];

export const loader = ({ paramsEntries }) => {
  const [keys, params] = paramsEntries;
  return GET(params);
};

export const Title = () => {
  const data = useLoaderData();
  return <h1>{data.title}</h1>;
};

<Title />
```

Pass `params` straight to a parametrized endpoint when only positional values
are needed; `keys` is there alongside it for cases like building a request
body or a cache key from the parameter names themselves. Either way, there's
no need to reconstruct an array from `params`/`useParams()` by hand.

> **Don't** reach for `Object.keys(route.params)`/`Object.values(route.params)`
> as a substitute. It happens to work today because JS object key order
> usually follows insertion order, but that's an implicit contract, not a
> guarantee tied to how the route declares its parameters - it can silently
> break for multi-param or splat routes, or if matching internals ever
> change. `paramsEntries` derives its order from the route's own declared
> parameter list, so it's correct by construction instead of by coincidence.

> **Important:** `loader` runs during resolution, before the component tree
> is built, so it never has access to `useParams()`, `useRoute()`, or any
> other hook - only to the `Route` object passed as its argument. Hooks
> remain the right tool inside actual components;
> `loader` is a pre-render step, not a rendered component.

## Navigation with `Link`

There is `Link` component at `components/Link.tsx` for your convenience:

```mdx
import Link from "~/components/Link"

Navigate to the <Link to={["blog/[slug]", "hello-world"]}>first post</Link>
or go <Link to={["index"]}>home</Link>.
```

The `to` prop accepts the same tuple as other frameworks - route name followed by parameters.
`Link.tsx` is type-checked, but the call site in an `.mdx` page is not,
so a wrong route name or a missing parameter surfaces at runtime rather than at build time.
Wrap navigation in a `.tsx` component where that matters.

> **Tip:** When `Link` is enabled in `components/mdx.ts` (the default),
> it can be used in pages without import - it is a global component provided via `MDXProvider`.

## Frontmatter & Head Injection

Frontmatter drives `<head>` content automatically. The SSR server reads
`title`, `description`, and the `head` array from frontmatter and injects
them into the HTML template:

```mdx
---
title: Getting Started
description: Set up your first MDX source folder.
head:
  - - meta
    - name: keywords
      content: mdx, kosmojs, getting started
  - - link
    - rel: canonical
      href: https://kosmojs.dev/docs/getting-started
---
```

Produces:

```html
<head>
  <title>Getting Started</title>
  <meta name="description" content="Set up your first MDX source folder.">
  <meta name="keywords" content="mdx, kosmojs, getting started">
  <link rel="canonical" href="https://kosmojs.dev/docs/getting-started">
</head>
```

This follows the same convention used by VitePress - no new syntax to learn.

## Application Structure

MDX folders get the same seeded foundation files as other frameworks,
keeping project structure consistent:

```txt
src/content/
├── app.mdx                ← global layout
├── router.ts              ← routes wired into the native router
├── index.html             ← HTML shell with placeholders
├── components/
│   ├── Link.tsx           ← navigation component
│   └── mdx.ts             ← MDXProvider component overrides
├── entry/
│   ├── client.ts          ← minimal client entry
│   └── server.ts          ← SSR rendering with Preact
└── pages/
    └── *.mdx              ← content pages, optionally exporting `loader`
```

### Router Configuration

`router.ts` follows the same `routerFactory` pattern as every other framework -
the only MDX-specific part is the `components` map handed to `createRouters` alongside the app,
so the MDXProvider overrides apply to every page.

```ts [router.ts]
import routerFactory, { createRouters } from "_/router";

import app from "./app.mdx";
import { components } from "./components/mdx"

export default routerFactory((routes) => {
  const { clientRouter, serverRouter } = createRouters(routes, { app, components });
  return {
    clientRouter() {
      return clientRouter()
    },
    serverRouter(url) {
      return serverRouter(url)
    },
  };
});
```

### Client/Server Entry

Both client and server entries follow the same `renderFactory` pattern as React/Solid/Vue.

* Client entry either renders the whole page on dev or hydrates the rendered SSR page.
* Server entry factory returns `renderToString` with `{ head, html }`. MDX renders
  static content, so it implements only `renderToString` - it is the one framework
  that omits `renderToStream`.

#### Client/Server Entry - entry/client.ts

```ts
// entry/client.ts
import renderFactory, {
  createRoutes,
  hydrate,
  mount,
} from "_/entry/client";

import routerFactory from "../router";

const routes = createRoutes();
const { clientRouter } = routerFactory(routes);

const root = document.getElementById("app");

if (root) {
  renderFactory(() => {
    return {
      hydrate() {
        return hydrate(() => clientRouter(), root);
      },
      mount() {
        return mount(() => clientRouter(), root);
      },
    };
  });
} else {
  console.error("❌ Root element not found!");
}

```

#### Client/Server Entry - entry/server.ts

```ts
// entry/server.ts
import renderFactory, {
  createRoutes,
  renderToString,
  // no renderToStream on MDX folders
} from "_/entry/server";

import routerFactory from "../router";

const routes = createRoutes();

const { serverRouter } = routerFactory(routes);

export default renderFactory(() => {
  return {
    async renderToString(url, { assets }) {
      return renderToString(
        () => serverRouter(url),
        { headerTags: assets.map(({ tag }) => tag) },
      );
    },
  };
});
```

## When to Use MDX vs Frameworks

| Use Case | MDX | React / SolidJS / Vue |
|---|---|---|
| Documentation sites | ✅ | ❌ Overkill |
| Marketing / landing pages | ✅ | ❌ Overkill |
| Blog with static content | ✅ | ❌ Overkill |
| Interactive dashboards | ❌ | ✅ |
| Apps with client-side state | ❌ | ✅ |
| Forms with real-time validation | ❌ | ✅ |

The rule is simple: if the source folder is primarily content with occasional
interactive components, use MDX. If it is primarily interactive
with occasional content, use React/Vue/Solid.

## Common Pitfalls

* **No TypeScript in MDX.** Keep typed code in `.tsx` files and import into MDX. MDX only supports plain JavaScript expressions.
* **Hooks at module scope.** `export const x = useHook()` runs on import, not during render. Always call hooks inside component functions.
* **`loader` can't use hooks.** `useParams()`, `useRoute()`, and any other hook only work inside a rendered component.
  `loader` runs before the tree exists - use the `Route` object passed as its argument (`paramsEntries`, `frontmatter`, etc.) instead.
* **Curly braces in prose.** `{...spread}` in markdown text is parsed as a JSX expression. Use backticks for code containing curly braces: `` `{...spread}` ``.
* **Layouts must be `.mdx`.** Plain `.md` files cannot render `{props.children}` and will not work as layouts.

---

---
url: /validation/intro.md
description: >-
  KosmoJS runtype validation automatically converts TypeScript types into JSON
  Schema with runtime validators. Write types once, get compile-time and runtime
  safety without schema duplication.
---

KosmoJS calls its approach **runtype validation**: your TypeScript types are
automatically converted into JSON Schema and validated at runtime.

> "Runtype" is a shorthand, not an industry standard you're expected to already know - a *run*time check derived from a *type*.
> If you've used Zod or Yup, this inverts the direction: instead of writing a schema and inferring a type from it,
> you write the type and the schema is derived from it.

No separate schema language to learn. No schemas drifting out of sync with your types.
One type definition becomes the source of truth for:

* runtime validation on the server
* client-side validation in typed fetch clients
* OpenAPI 3.1 specification

## Understanding Runtype Validation

When you provide type annotations to your route parameters, payloads, and responses,
`TypeScript` gives you compile-time checking - autocomplete, refactoring safety, and error detection before you run your code.

But compile-time checks don't protect you at runtime.
When actual HTTP requests arrive with unpredictable data from the outside world,
`TypeScript` is no longer in the picture.

Runtype validation closes this gap.
The same type definitions that give you compile-time safety
also produce validation logic that runs when requests arrive,
ensuring that incoming data actually matches what your types promise.

## End-to-End Validation

Runtype validation happens at both ends:
the client validates before sending requests,
and the server validates before processing them.

Fetch clients validate request data on the client side before making any network request.
If validation fails, the client throws immediately - no round trip needed.

This uses the exact same schemas that validate on the server,
so what the client considers valid and what the server accepts are always in sync.

Double validation is not a performance cost - it's a performance gain.
Invalid requests never reach your server, saving bandwidth and compute.
Users also get instant feedback instead of waiting for a server response.

## How Derivation Works

KosmoJS uses AST parsing to extract types from your route files,
then AOT compilation to emit high-performance validation routines in your `lib` directory.

For each validated type, [TypeBox](https://github.com/sinclairzx81/typebox) produces a JSON Schema
and a compiled validator function tailored specifically to that structure -
direct property checks with minimal overhead, not a generic JSON Schema interpreter.

The derived code lives in `lib`, keeping your source directories focused on business logic.
At production build time it's bundled like any other dependency.

You don't need to read or understand the derived code to use validation.
If you're curious about performance characteristics or need to troubleshoot,
see [Validation Performance](/validation/performance).

---

---
url: /validation/params.md
description: >-
  Validate route parameters at runtime with type refinements using defineRoute
  type arguments. Convert string URL parameters to validated numbers, integers,
  or constrained values with VRefine.
---

Route parameters are extracted from the URL path as strings - that's just how URLs work.
But you often need more than a string: a numeric ID, a positive integer, a value from a fixed set or of a specific pattern, uuid, date, etc.

KosmoJS lets you express these requirements directly in the type system.

## Params Refinements

Pass a tuple as the second type argument to `defineRoute`.
Each position refines the corresponding parameter in route order.

For a route at `api/users/[id]/index.ts`:

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

export default defineRoute<"users/[id]", [
  number // [!code hl]
]>(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.validated.params; // typed as number // [!code hl]
  }),
]);
```

A request to `/api/users/abc` is rejected with a 400 before your handler runs.

::: tip Numeric params are coerced for you
A URL param arrives as a string, but when you type it as `number`,
KosmoJS coerces it before validation - `"123"` becomes `123`.

A non-numeric value like `"abc"` is left as-is and fails the number check, producing a clean 400.

So you write `number` (or a numeric `VRefine`) and read a real number from `ctx.validated.params`; no manual coercion needed.
:::

Access validated parameters through `ctx.validated.params` - it carries the refined type, not the raw string.
The underlying raw params still exists if you need the original:

* Hono - `ctx.req.param()`
* H3 - `event.context.params`
* Koa - `ctx.params`

Refine further with `VRefine` (globally available, no import needed):

```ts [api/users/[id]/index.ts]
export default defineRoute<"users/[id]", [
  VRefine<number, { minimum: 1, multipleOf: 1 }> // positive integer // [!code hl]
]>(({ GET }) => [
  // ...
]);
```

[More on VRefine ›](/validation/refine)

## Multiple Parameters

For routes with multiple parameters, each tuple position maps to the corresponding param.
Positions are optional - omit any you don't need to refine.

```ts [api/users/[id]/[view]/index.ts]
export default defineRoute<"users/[id]/[view]", [
  VRefine<number, { minimum: 1, multipleOf: 1 }>, // id // [!code hl]
  "profile" | "settings" | "data"                 // view // [!code hl]
]>(({ GET }) => [
  GET(async (ctx) => {
    const { id, view } = ctx.validated.params; // [!code hl]
  }),
]);
```

Refinements are positional, not name-based - renaming `[id]` to `[userId]` requires no changes here.

## Overriding the Default

Params validation runs in the `validate:params` slot.
Claim that slot and your middleware runs instead of it.

Use it when no refinement can express the check.
Resolving a slug against the database, for instance.

Only that target changes. `ctx.validated.params` is no longer set.
Every other target keeps its own validator.
[Details ›](/backend/middleware#overriding-validation)

---

---
url: /validation/payload.md
description: >-
  Validate request payloads with inline TypeScript types or imported type
  definitions. Support for nested structures, conditional validation, generics,
  and complex domain models with VRefine constraints.
---

Payload validation covers everything your API receives from clients:
query parameters, headers, cookies for any method,
and request bodies for POST/PUT/PATCH.

KosmoJS makes payload validation straightforward by letting you express validation rules
directly through `TypeScript` types.

You write the type once, and it serves both as compile-time safety
and runtime validation enforcement.

## Validation Targets

Each target maps to a part of the incoming HTTP request.

**Metadata targets** (all HTTP methods):

* `query` - URL query parameters (`?page=1&limit=10`)
* `headers` - HTTP request headers
* `cookies` - HTTP cookies

**Body targets** (POST/PUT/PATCH only):

* `json` - JSON request body
* `form` - URL-encoded or multipart form
* `raw` - plain text, binary, Buffer, ArrayBuffer, Blob

Any combination of metadata targets is valid.

> Body targets are mutually exclusive - one per handler.

```ts
// ✅ Multiple metadata targets + one body target
POST<{
  query: { page?: number };
  headers: { authorization: string };
  json: { title: string };
}>

// ✅ Only metadata targets
GET<{
  query: { search: string };
  headers: { 'x-api-key': string };
  cookies: { session: string };
}>

// ❌ Multiple body targets
POST<{
  json: { title: string };
  form: { title: string };  // Error: only one body target allowed
}>

// ❌ Body target on GET
GET<{
  json: { data: string };  // Error: GET cannot have request body
}>
```

Invalid configurations are detected at dev time and disabled automatically.

## Coerced values

Everything off the wire is a string.
Some primitive values are coerced automatically, when typed accordingly and content is appropriate.

**Numbers - coerced in route params and `query`.**

Typing a field as `number` turns `"10"` into `10`.

```ts
GET<{
  query: { page?: number; }; // coerced: "2" -> 2
}>
```

**Booleans** - coerced in **`query`** only.

Typing a field as `boolean` turns `"true"`/`"false"` into `true`/`false`.

```ts
GET<{
  query: { draft?: boolean; }; // coerced: "true" -> true
}>
```

> Params are path segments where a boolean is meaningless, so they never coerce booleans.

Coercion only maps the exact expected forms:

* a `number` field coerce only numeric values
* a `boolean` field coerce only `"true"`/`"false"` values

Everything else stays a string and fails validation cleanly.

`headers`/`cookies`/`form`/`raw` never coerce.

`json` carries real numbers and booleans natively, no coercion needed.

## Basic Payload Validation

Pass the payload type as the first type argument to your method handler:

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

export default defineRoute<"posts">(({ POST }) => [
  POST<{
    json: {
      title: VRefine<string, { minLength: 1, maxLength: 255 }>;
      content: string;
      tags: string[];
      isPublished: boolean;
      scheduledPublishAt?: VRefine<string, { format: "date-time" }>;
    },
  }>(async (ctx) => {
    const { title, content, tags } = ctx.validated.json; // [!code hl]
  }),
]);
```

Optional fields (`?`) can be omitted entirely. When present, they must still pass their type and refinement constraints.

Notice how `VRefine` is used to add validation constraints to specific fields.

The `minLength` and `maxLength` constraints ensure titles aren't empty or excessively long.

The `format: "date-time"` constraint leverages JSON Schema's format validation
to ensure dates are properly formatted.

Without `VRefine`, fields are validated only for their basic type - a string must be a string,
an array must be an array, but no additional constraints apply.

[More on VRefine ›](/validation/refine)

## Complex Nested Structures

Since validation rules are just `TypeScript` types, nested objects, union types,
conditional fields, referenced types - all work naturally:

```ts [api/checkout/index.ts]
import type { BillingAddress } from "~/types/checkout";

type PaymentMethod = {
  type: "card" | "wallet";
  card?: {
    number: VRefine<string, { pattern: "^[0-9]{13,19}$" }>;
    expMonth: VRefine<number, { minimum: 1, maximum: 12 }>;
    expYear: number;
    cvc: VRefine<string, { pattern: "^[0-9]{3,4}$" }>;
    holderName: string;
  };
  wallet?: {
    walletId: string;
    token: VRefine<string, { minLength: 1, maxLength: 500 }>;
  };
};

type Payload = {
  orderId: VRefine<string, { pattern: "^[a-zA-Z0-9_-]{1,50}$" }>;
  amount: VRefine<number, { minimum: 0.01, maximum: 1000000 }>;
  currency: VRefine<string, { pattern: "^[A-Z]{3}$" }>;
  paymentMethod: PaymentMethod;
  billingAddress: BillingAddress;
};

export default defineRoute<"checkout">(({ POST }) => [
  POST<{
    json: Payload,
  }>(async (ctx) => {
    // every field validated before handler runs
  }),
]);
```

## Combining Multiple Targets

You can validate multiple parts of the request simultaneously by specifying multiple targets.
This is particularly useful for endpoints that need to validate query parameters, headers, and request body together:

```ts [api/posts/search.ts]
export default defineRoute<"posts/search">(({ POST }) => [
  POST<{
    query: {
      page: VRefine<number, { minimum: 1 }>;
      limit: VRefine<number, { minimum: 1, maximum: 100 }>;
      sortBy?: "date" | "title" | "views";
    };
    headers: {
      authorization: VRefine<string, { pattern: "^Bearer .+" }>;
      "x-api-version"?: string;
    };
    cookies: {
      session: string;
    };
    json: {
      filters: {
        tags?: string[];
        status?: "draft" | "published" | "archived";
        dateRange?: {
          from: VRefine<string, { format: "date-time" }>;
          to: VRefine<string, { format: "date-time" }>;
        };
      };
    };
  }>(async (ctx) => {
    const { page, limit, sortBy } = ctx.validated.query;
    const { authorization } = ctx.validated.headers;
    const { session } = ctx.validated.cookies;
    const { filters } = ctx.validated.json;
  }),
]);
```

Each target is validated independently. All must pass before your handler executes.

## Body Formats

### JSON

```ts
POST<{
  json: {
    name: string;
    email: VRefine<string, { format: "email" }>;
  };
}>(async (ctx) => {
  const { name, email } = ctx.validated.json;
})
```

### Form (URL-encoded)

```ts
POST<{
  form: {
    username: VRefine<string, { minLength: 3, maxLength: 20 }>;
    password: VRefine<string, { minLength: 8 }>;
  };
}>(async (ctx) => {
  const { username, password } = ctx.validated.form;
})
```

### Multipart (file uploads)

```ts
POST<{
  form: {
    file: File;
    title: string;
    description?: string;
  };
}>(async (ctx) => {
  const { file, title, description } = ctx.validated.form;
})
```

### Raw

```ts
POST<{
  raw: VRefine<string, { minLength: 1, maxLength: 10000 }>;
}>(async (ctx) => {
  const rawContent = ctx.validated.raw;
})
```

**Worth noting:** you can only specify **one body target** per handler (`json`, `form` or `raw`),
but you can combine it with any number of metadata targets (`query`, `headers`, `cookies`).

## Referenced Types

As your application grows, defining complex types inline becomes unwieldy.
You'll want to define types once and reuse them across multiple routes.

KosmoJS fully supports this pattern - you can define types in separate files,
import them where needed, and use them for validation just like inline types.

Suppose you have a file defining user-related types:

```ts [types/user.ts]
export type UserProfile = {
  name: VRefine<string, { minLength: 1, maxLength: 255 }>;
  email: VRefine<string, { format: "email" }>;
};

export type UserPreferences = {
  theme: "light" | "dark";
  notifications: NotificationPreferences;
};

type NotificationPreferences = {
  enabled: boolean;
};
```

```ts [types/api-payload.ts]
import type { UserProfile, UserPreferences } from "./user";

export type Payload<T> = {
  data: T;
  meta: {
    pagination?: { page: number; limit: number; total: number };
    cache: { ttl: number; revalidate: boolean };
  };
};

export type User = {
  id: number;
  profile: UserProfile;
  preferences: UserPreferences;
  posts: Post[];
};

export type Post = {
  id: VRefine<number, { minimum: 1, multipleOf: 1 }>;
  title: string;
  tags: { id: string; name: string }[];
  stats?: { views: number; likes: number };
};
```

Now you can use these types in any route by importing them:

```ts [api/users/index.ts]
import type { User, Payload } from "~/types/api-payload";
import { defineRoute } from "_/api";

export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: Payload<User>, // [!code hl]
  }>(async (ctx) => {
    // ctx.validated.json typed as Payload<User>
  }),
]);
```

Generics are resolved and every referenced type traced, producing a complete validation schema.
Update a shared type and validation updates everywhere it's used.

Different routes, same wrapper:

```ts [api/posts/index.ts]
import type { Post, Payload } from "~/types/api-payload";

export default defineRoute<"posts">(({ POST }) => [
  POST<{
    json: Payload<Post>, // [!code hl]
  }>(async (ctx) => {}),
]);
```

## Overriding the Default

Every target has its own slot: `validate:json`, `validate:form`, `validate:raw`.

Claim one and your middleware runs instead of the built-in validator.
Use it for a body format no schema describes, or a check that has to hit the database.

Replacing one target leaves the rest alone.
And `ctx.bodyparser.<target>()` is cached, so your validator and your handler can both read the body.
[Details ›](/backend/middleware#overriding-validation)

---

---
url: /validation/response.md
description: >-
  Validate API responses before sending to clients. Catch bugs where handlers
  return incomplete objects, wrong types, or unexpected structures. Enabled by
  default in development; opt in per handler for production.
---

Outgoing responses can be validated too. Use the `response` property to declare the expected status code,
content type, and body schema:

```ts [api/users/index.ts]
import type { User } from "~/types/api-payload";
import { defineRoute } from "_/api";

export default defineRoute<"users">(({ GET }) => [
  GET<{
    response: [200, "json", User], // [!code hl]
  }>(async (ctx) => {
    // response must comply with the defined schema
  }),
]);
```

Before sending, KosmoJS checks that the actual status, content type, and body match the schema.
If anything is off - a missing field, a type mismatch, a constraint violation - it throws a `ValidationError`
instead of sending malformed data to the client.

## Development vs Production

Response validation is environment-aware:

* **Development / test**: every declared response schema is validated at runtime.
  Opt out per handler with [runtimeValidation: false](/validation/skip-validation).
* **Production builds**: response validation is **disabled by default**.
  To enable it running in production, set `runtimeValidation: true` on the response target:

```ts [api/users/index.ts]
export default defineRoute<"users">(({ GET }) => [
  GET<{
    response: [200, "json", User],
  },
  {
    response: { // [!code ++:3] validate this response in production too
      runtimeValidation: true,
    }
  }>(async (ctx) => {
    // ...
  }),
]);
```

There is no global switch - each handler enables production response validation for itself.
This is deliberate: validating every outgoing response costs CPU on your hottest path,
so production validation is a per-endpoint decision, not a blanket default.

Note the asymmetry with request validation: payloads and parameters coming *into* your API are always validated,
in every environment (unless explicitly skipped) - they cross a trust boundary.
Responses are produced by your own code, so by default they are checked only where bugs are cheap: in development.

Response validation is especially valuable for data sourced from databases or third-party APIs,
where the shape can change without warning. If an endpoint serves such data and malformed output
would be worse than a thrown error, that endpoint is a candidate for `runtimeValidation: true`.

Defining a response schema also enables automatic `OpenAPI` derivation -
type safety and documentation in one step.
[Details ›](/openapi)

## Overriding the Default

Response validation runs in the `validate:response` slot.
Claim that slot and your middleware decides what a valid response looks like.
The built-in check stops running.

Use it for responses no schema can describe - a stream, for example.
[Details ›](/backend/middleware#overriding-validation)

---

---
url: /validation/refine.md
description: >-
  Advanced validation constraints with VRefine using JSON Schema keywords.
  Validate string formats, numeric ranges, array constraints, and custom
  patterns directly in TypeScript types.
---

`VRefine` adds JSON Schema constraints to any type - primitives, arrays, and objects alike.

```ts
VRefine<number, { minimum: 1000, maximum: 1_000_000 }>
```

> It is globally available - no import needed.

The first argument is the base type, the second is any valid
[JSON Schema validation keyword](https://json-schema.org/draft/2020-12/json-schema-validation.html).
The full keyword set, grouped as in the spec, is below - everything at a glance.

## Validation keywords

### Strings

| Keyword | Meaning |
| --- | --- |
| `minLength` | Minimum character count |
| `maxLength` | Maximum character count |
| `pattern` | Must match the ECMA-262 regular expression |
| `format` | Must match a named format - see [the format table](#formats) |

```ts
VRefine<string, { minLength: 3, maxLength: 50 }>
VRefine<string, { pattern: "^[a-z0-9][a-z0-9_-]*$" }>
VRefine<string, { format: "email" }>
```

### Numbers

| Keyword | Meaning |
| --- | --- |
| `minimum` | Inclusive lower bound |
| `maximum` | Inclusive upper bound |
| `exclusiveMinimum` | Exclusive lower bound |
| `exclusiveMaximum` | Exclusive upper bound |
| `multipleOf` | Must be evenly divisible by the given value |

```ts
VRefine<number, { minimum: 1, maximum: 100, multipleOf: 1 }>
VRefine<number, { exclusiveMinimum: 0 }>
```

### Arrays

| Keyword | Meaning |
| --- | --- |
| `minItems` | Minimum element count |
| `maxItems` | Maximum element count |
| `uniqueItems` | All elements must be distinct |
| `contains` | At least one element must match the given schema, written inline as a schema literal |
| `minContains` / `maxContains` | Bounds on how many elements may match `contains` |

```ts
VRefine<Array<string>, { minItems: 1, maxItems: 20 }>
VRefine<Array<VRefine<string, { format: "email" }>>, { uniqueItems: true }>

// at least one "admin" entry
VRefine<string[], { contains: { type: "string"; const: "admin" } }>

// one or two elements matching the nested schema - any keyword combination works,
// including pattern, enum, format, length bounds
VRefine<string[], {
  contains: { type: "string"; const: "premium" };
  minContains: 1;
  maxContains: 2;
}>
```

### Objects

| Keyword | Meaning |
| --- | --- |
| `minProperties` | Minimum property count |
| `maxProperties` | Maximum property count |
| `required` | Array of mandatory property names - normally implied by TypeScript optionality (`?`), reach for it only on open shapes like `Record` |
| `dependentRequired` | Properties required when another property is present |

```ts
VRefine<Record<string, string>, { maxProperties: 20 }>
```

### Any instance type

| Keyword | Meaning |
| --- | --- |
| `enum` | Must equal one of the listed values - as a top-level constraint a TypeScript literal union (`"a" \| "b"`) expresses this natively; inside a nested schema like `contains` it is the way to say it |
| `const` | Must equal a specific value - as a top-level constraint a TypeScript literal type (`"a"`, `2`, `true`) expresses this natively; inside a nested schema like `contains` it is the way to say it |
| `type` | Constrains the JSON type - redundant at the top level (the base type already is the type), required inside nested schemas like `contains` |

### Content keywords

`contentEncoding`, `contentMediaType`, and `contentSchema` describe how to interpret
string contents (e.g. base64 payloads). Per the spec they are **annotations, not
assertions** - they document, they don't reject. Fine to attach for OpenAPI output;
don't expect them to validate anything.

## Formats

`format: "..."` values are validated at runtime. Every format defined by the
2020-12 spec is supported, plus two TypeBox extras at the end:

| Format | Validates |
| --- | --- |
| `date-time` | RFC 3339 timestamp, e.g. `2026-08-23T07:00:00Z` |
| `date` | Full date, e.g. `2026-08-23` |
| `time` | Time of day, e.g. `07:00:00Z` |
| `duration` | ISO 8601 duration, e.g. `P3DT4H` |
| `email` | Email address |
| `idn-email` | Internationalized email address |
| `hostname` | DNS hostname |
| `idn-hostname` | Internationalized hostname |
| `ipv4` | IPv4 address |
| `ipv6` | IPv6 address |
| `uri` | Absolute URI |
| `uri-reference` | URI or relative reference |
| `iri` | Internationalized URI |
| `iri-reference` | IRI or relative reference |
| `uuid` | UUID, e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` |
| `uri-template` | RFC 6570 URI template |
| `json-pointer` | JSON Pointer, e.g. `/foo/0` |
| `relative-json-pointer` | Relative JSON Pointer |
| `regex` | ECMA-262 regular expression source |
| `url` | URL (TypeBox extra, not in the spec) |
| `json-pointer-uri-fragment` | JSON Pointer in URI fragment form (TypeBox extra) |

```ts
VRefine<string, { format: "uuid" }>    // params: id: must be a valid UUID
VRefine<string, { format: "email" }>   // json: from -> email: must be a valid email address
```

## Integers

One common gotcha: `number` alone allows decimals. If you need a true integer, use `multipleOf: 1` -
it means the value must be evenly divisible by 1:

```ts
// allows 1000.5 - probably not what you want
VRefine<number, { minimum: 1000, maximum: 1_000_000 }>

// integers only
VRefine<number, { minimum: 1000, maximum: 1_000_000, multipleOf: 1 }>
```

This matters especially for database IDs, where a float would pass validation
but get rejected at the query level - turning a clear validation error into a confusing DB error.

## Keep the Wrapping Brackets Literal

One rule covers every place KosmoJS reads structure out of your type arguments:

::: tip The rule
**The wrapping `[]` and `{}` must be written literally. Anything *inside* them can be aliased.**
:::

That applies to three positions:

```ts
// the VRefine constraint object
VRefine<string, { pattern: "^[A-Z]{3}$" }>

// the params refinement tuple
defineRoute<"users/[id]/[action]", [UserID, UserAction]>

// the response tuple
POST<{ response: [200, "json", User] }>
```

In each case the brackets stay where you can see them, while the values inside are free to be named types - local or imported:

```ts
// ✅ contents aliased, brackets kept
type Pattern = "^[A-Z]{3}$";
VRefine<string, { pattern: Pattern }>

type UserID = VRefine<number, { minimum: 1, multipleOf: 1 }>;
defineRoute<"users/[id]", [UserID]>

type User = { id: number; name: string };
POST<{ response: [200, "json", User] }>
```

```ts
// ❌ the brackets themselves hidden behind an alias
type Params = [UserID, UserAction];
defineRoute<"users/[id]/[action]", Params>

type ResponseT = [200, "json", User];
POST<{ response: ResponseT }>
```

The base type of `VRefine` (its first argument) is unrestricted either way -
`VRefine<MyStringAlias, { ... }>` and imported base types resolve normally.

### Why the brackets matter

These positions are read **structurally**, from the source: which tuple slot maps to which route parameter,
which slot carries the status code versus the body.
An alias that hides the brackets gives it an identifier where it expected a shape, and there is nothing to destructure.

That failure is silent, and it differs by position:

| Position | If the brackets are hidden behind an alias |
|---|---|
| `params` tuple | the schema does not build - **every** request is rejected with a 400 |
| `response` tuple | **no schema is built at all** - response validation never runs, and the route gets no [ResponseT](/fetch/type-safety#response-types) entry |

Neither raises a compile error, so nothing points at the alias.
If a route rejects input you know is valid, or a response you declared is silently not validated, check the brackets first.

> This is one of the mistakes that typecheck cleanly and fail at runtime.
> [Silent Failure Checklist ›](/validation/gotchas)

---

---
url: /validation/skip-validation.md
description: >-
  Set runtimeValidation option to false to keep TypeScript type checking without
  runtime validation for gradual adoption, performance optimization, or trusted
  internal endpoints.
---

There are cases where you want `TypeScript` type checking without the runtime validation overhead -
rapid iteration on payload structures, or trusted internal endpoints where you control both sides.

The second type argument to your handler accepts per-target options.
Set `runtimeValidation: false` to keep compile-time types while skipping runtime checks for that target:

```ts [api/example/index.ts]
export default defineRoute<"example">(({ POST }) => [
  POST<{
    json: Payload<User>,
  },
  {
    json: {
      runtimeValidation: false, // [!code hl]
    }
  }>(async (ctx) => {
    // ctx.validated.json is not available - use the bodyparser directly
    const user = await ctx.bodyparser.json<User>()
  }),
]);
```

This works for both payload and response targets. Route parameter validation cannot be skipped -
parameters are part of the URL structure and always validated.

For response targets the flag also works the other way: production builds skip response
validation unless you set `runtimeValidation: true` on the handler.
[Details ›](/validation/response)

Use this sparingly. Runtime validation is what catches the bugs `TypeScript` can't -
mismatched database responses, unexpected client payloads, API drift.
Skipping it is a conscious tradeoff, not a default.

---

---
url: /validation/error-handling.md
description: >-
  Handle ValidationError instances with detailed error information including
  scope, error messages, field paths, and structured ValidationErrorEntry data.
---

When validation fails - on parameters, request payload, or response - KosmoJS throws a `ValidationError`
with detailed information about what went wrong and where.

Your `api/errors.ts` is the central place to handle it. The seeded file gives you a working default;
customize it freely to add logging, change response formats, or handle specific error types differently.
[Details ›](/backend/error-handling)

## ValidationError Properties

```ts
export class ValidationError extends Error {
  public target: ValidationTarget;   // which part of the request failed
  public errors: Array<ValidationErrorEntry> = [];
  public errorMessage: string;       // all errors as a single readable string
  public errorSummary: string;       // e.g. "2 validation errors found across 2 fields"
  public route: string;
  public data: unknown;              // the data that failed validation
}

export type ValidationErrorEntry = {
  keyword: string;                   // JSON Schema keyword that triggered the error
  path: string;                      // path to the invalid field
  message: string;                   // human-readable description
  params?: Record<string, unknown>;  // constraint details, e.g. { limit: 5 }
  code?: string;                     // optional code for i18n / custom handling
};
```

The `target` property tells you exactly which part of the request failed:
`"params"`, `"query"`, `"headers"`, `"cookies"`, `"json"`, `"form"`, `"raw"`, or `"response"`.

**Common handling patterns:**

### ValidationError Properties - Hono

```ts
// Hono: api/errors.ts

// All errors as a readable string
if (error instanceof ValidationError) {
  const { target, errorMessage } = error;
  // e.g. "Validation failed: user: missing required properties: "email", "name";
  //       password: must be at least 8 characters long"
  return ctx.json({ error: errorMessage }, 400);
}

// Field-level errors (useful for form responses)
if (error instanceof ValidationError) {
  const messages = error.errors.map(e => `${e.path}: ${e.message}`);
  return ctx.json({ error: "validation_error", target: error.target, messages }, 400);
}

// Log the invalid data, return a summary
if (error instanceof ValidationError) {
  logger.error("Validation failed", { target: error.target, data: error.data });
  return ctx.json({ error: error.errorSummary }, 400);
}
```

### ValidationError Properties - H3

```ts
// H3: api/errors.ts

// All errors as a readable string
if (error instanceof ValidationError) {
  const { target, errorMessage } = error;
  // e.g. "Validation failed: user: missing required properties: "email", "name";
  //       password: must be at least 8 characters long"
  event.res.status = 400;
  return { error: errorMessage };
}

// Field-level errors (useful for form responses)
if (error instanceof ValidationError) {
  const messages = error.errors.map(e => `${e.path}: ${e.message}`);
  event.res.status = 400;
  return { error: "validation_error", target: error.target, messages };
}

// Log the invalid data, return a summary
if (error instanceof ValidationError) {
  logger.error("Validation failed", { target: error.target, data: error.data });
  event.res.status = 400;
  return { error: error.errorSummary };
}
```

### ValidationError Properties - Koa

```ts
// Koa: api/errors.ts

// All errors as a readable string
if (error instanceof ValidationError) {
  const { target, errorMessage } = error;
  // e.g. "Validation failed: user: missing required properties: "email", "name";
  //       password: must be at least 8 characters long"
  ctx.status = 400;
  ctx.body = { error: errorMessage };
}

// Field-level errors (useful for form responses)
if (error instanceof ValidationError) {
  const messages = error.errors.map(e => `${e.path}: ${e.message}`);
  ctx.status = 400;
  ctx.body = { error: "validation_error", target: error.target, messages };
}

// Log the invalid data, return a summary
if (error instanceof ValidationError) {
  logger.error("Validation failed", { target: error.target, data: error.data });
  ctx.status = 400;
  ctx.body = { error: error.errorSummary };
}
```

## Custom Error Messages

The second type argument to your handler also accepts custom error messages per target.
Use `error` as a fallback and `error.fieldName` for field-specific overrides:

```ts [api/users/index.ts]
export default defineRoute<"users">(({ POST }) => [
  POST<
    {
      json: {
        id: number;
        email: string;
        age: number;
      };
    },
    {
      json: {
        error: "Invalid user data provided",
        "error.id": "User ID must be a valid number",
        "error.email": "Please provide a valid email address",
        "error.age": "Age must be a number",
      };
    }
  >(async (ctx) => {
    const { id, email, age } = ctx.validated.json;
  }),
]);
```

Each target has its own message set. For nested fields, use dot notation:

```ts
{
  json: {
    error: "Invalid order data",
    "error.order.items": "Order must contain at least one item",
    "error.order.shipping.address.postalCode": "Invalid postal code format",
  }
}
```

When validation fails, KosmoJS uses the most specific message available -
field-specific first, falling back to the generic `error` if no match is found.
Custom messages appear in the `message` field of each `ValidationErrorEntry`,
so your existing error handler picks them up automatically.

---

---
url: /validation/naming-conventions.md
description: >-
  Avoid TypeScript built-in type names when defining types for validation. Use
  suffix T or prefix T conventions to prevent runtime validation failures.
---

Avoid naming your types after TypeScript/JavaScript built-ins like `Event`, `Response`, `Request`, or `Error`.
These names compile fine, but cause silent failures during runtime validation.

## Why This Matters

When KosmoJS flattens types for schema derivation, built-in names are referenced as-is
rather than resolved to your custom definition. The validator sees the built-in, not your type,
and validation fails at runtime without a compile-time warning.

```ts
// ❌ Compiles fine, breaks at runtime
type Event = { id: number; name: string; timestamp: string };

// ✅ Works correctly
type EventT = { id: number; name: string; timestamp: string };
type TEvent = { id: number; name: string; timestamp: string }; // also fine
```

Use a consistent `T` suffix (`EventT`, `ResponseT`) or prefix (`TEvent`, `TResponse`) throughout your project.
If validation fails unexpectedly despite correct type definitions, a naming conflict is the first thing to check.

## Common Built-ins to Avoid

**DOM:** `Event`, `Element`, `Document`, `Window`, `Node`, `HTMLElement`, `EventTarget`, `CustomEvent`

**Web APIs:** `Response`, `Request`, `Headers`, `Body`, `Blob`, `File`, `FormData`, `URLSearchParams`, `WebSocket`

**JavaScript:** `Error`, `Date`, `RegExp`, `Promise`, `Symbol`, `Map`, `Set`, `Array`, `Object`, `String`, `Number`

**TypeScript utilities:** `Partial`, `Required`, `Readonly`, `Pick`, `Omit`, `Record`, `Exclude`, `Extract`, `NonNullable`

**Node.js:** `Buffer`, `Stream`, `EventEmitter`, `Timeout`

For the full list, see the [TFusion builtins reference](https://github.com/sleewoo/tfusion/blob/main/src/builtins.ts).

> This is one of four mistakes that typecheck cleanly and fail at runtime.
> [Silent Failure Checklist ›](/validation/gotchas)

---

---
url: /validation/gotchas.md
description: >-
  The four validation mistakes that typecheck cleanly and fail at runtime -
  non-inline VRefine constraints, built-in type names, float IDs, and
  non-coercing targets.
---

Most mistakes in KosmoJS are compile errors. Four are not: they typecheck cleanly and then misbehave at runtime.

They share a shape - your types are flattened into schema text, and a few things don't survive that trip.

**If validation is rejecting data that looks obviously valid, work down this list first.**

## 1. A wrapping bracket hidden behind an alias

KosmoJS reads three positions **structurally**, out of the source:
the `VRefine` constraint object, the params refinement tuple, and the response tuple.
In all three, the wrapping `{}` or `[]` must be written literally.

**Anything inside them can be aliased** - local or imported. It is only the brackets
themselves that must stay visible.

```ts
// ✅ contents aliased, brackets kept
type Pattern = "^[A-Z]{3}$";
VRefine<string, { pattern: Pattern }>

type UserID = VRefine<number, { minimum: 1, multipleOf: 1 }>;
defineRoute<"users/[id]", [UserID]>
```

```ts
// ❌ the brackets themselves behind an alias
type Params = [UserID, UserAction];
defineRoute<"users/[id]/[action]", Params>

type ResponseT = [200, "json", User];
POST<{ response: ResponseT }>
```

Both forms typecheck. KosmoJS, though, expected a shape and got an identifier,
with nothing to destructure - so it fails, silently, and differently per position:

| Position | If the brackets are hidden |
|---|---|
| `params` tuple | schema does not build - **every** request 400s, including valid ones |
| `response` tuple | **no schema built** - response validation never runs, and the route gets no `ResponseT` entry |

**Symptom:** a route rejects input you know is good, or a response you declared is quietly
never validated - with no compile error pointing at the alias.
[Details ›](/validation/refine#keep-the-wrapping-brackets-literal)

## 2. A type named after a built-in

Name a type `Event`, `Response`, `Date`, `Record`, `Error`, `Buffer` - or any other
JS/DOM/TS built-in - and the flattener references the built-in, not your definition.

```ts
// ❌ compiles, validates against the DOM Event
type Event = { id: number; name: string };

// ✅
type EventT = { id: number; name: string };
type TEvent = { id: number; name: string };
```

Adopt a `T` prefix or suffix consistently across the project.

**Symptom:** validation fails (or passes) in ways that make no sense for the type you wrote, with no compile-time warning.
[Full list of names to avoid ›](/validation/naming-conventions)

## 3. `number` where you meant integer

Normally, plain `number` allows decimals. A float ID passes validation and is then rejected by your database -
turning a clean 400 into a confusing query error further downstream.

```ts
// ❌ 1000.5 passes
VRefine<number, { minimum: 1 }>

// ✅ integers only
VRefine<number, { minimum: 1, multipleOf: 1 }>
```

**Symptom:** a DB driver error instead of a validation error.
[Details ›](/validation/refine#integers)

## 4. A non-string type on a target that doesn't coerce

Everything off the wire is a string. Only `query` coerces numbers *and* booleans,
and route `params` coerce numbers only.

`headers`, `cookies`, `form` and `raw` never coerce anything.

| Target | `number` | `boolean` |
|---|:---:|:---:|
| `params` | ✅ coerced | ❌ never (a boolean path segment is meaningless) |
| `query` | ✅ coerced | ✅ coerced (`"true"` / `"false"`) |
| `json` | ✅ native | ✅ native |
| `headers` · `cookies` · `form` · `raw` | ❌ | ❌ |

```ts
// ❌ never passes - form values are strings
POST<{ form: { age: number; consented: boolean } }>

// ✅ accept the wire format, convert in the handler
POST<{ form: { age: string; consented: "true" | "false" | "on" | "off" } }>
```

**Symptom:** a form or header field always fails validation no matter what is sent.
[Details ›](/validation/payload#coerced-values)

## Two more that aren't silent, but surprise people

**A missing `response` means no `ResponseT` entry.** Response typing on the client is opt-in:
declare `response` on the handler and you get response validation,
an OpenAPI response, and a `ResponseT["route"]["GET"]` entry together.
Omit it and you get none of the three.
[Details ›](/fetch/type-safety#response-types)

**Response validation is off in production by default.** Requests are always validated;
responses are validated in development and test only,
unless you opt a specific handler in with `runtimeValidation: true`.
There is no global switch.
[Details ›](/validation/response#development-vs-production)

## When Nothing Above Fits

Rebuilding is the blunt instrument, and occasionally the right one.

Remove `lib/` dir and restart dev server.

That forces a full rebuild of every schema - minutes on a large project, so it is not part of the normal loop.
Reach for it when you suspect stale derived output rather than a mistake in your types.
[Details ›](/validation/performance#when-it-becomes-noticeable)

---

---
url: /validation/performance.md
description: >-
  Understand KosmoJS validation performance with TypeScript compiler analysis,
  intelligent caching, and background processing that doesn't impact development
  workflow.
---

Schema derivation uses TypeScript's compiler API to trace your types - including all referenced files -
and build a complete dependency graph. This is what makes pure-TypeScript validation possible,
with a brief derivation step as the tradeoff.

Derivation time scales with type complexity. Simple routes are near-instant;
routes with deep hierarchies and many dependencies may take a few seconds.
In practice this rarely affects you - derivation runs in parallel with the Vite dev server,
and results are cached per file. Schemas are only recomputed when the route file or one of its type dependencies changes.

By the time you've saved a file and switched to the browser, the schema is ready.

## When It Becomes Noticeable

Full rebuilds happen in a few specific situations:

* Deleting the `lib` folder manually
* KosmoJS releasing an update that bumps the cache version

For large projects with many routes, a full rebuild can take several minutes.
This is the same category of thing as clearing `node_modules` or regenerating a Prisma client -
infrequent and expected, not part of the normal edit-test cycle.

## Machine Time vs Human Time

Zod, Yup etc. have zero derivation overhead - because you write the schemas yourself.
That eliminates derivation time but adds an ongoing maintenance cost.

KosmoJS trades a few seconds of machine time for eliminating that manual work entirely.
For most workflows, that's a good deal.

As the `TypeScript` ecosystem evolves - particularly native implementations that
[ts-morph](https://ts-morph.com/) and [TFusion](https://github.com/sleewoo/tfusion) may leverage -
derivation performance will likely improve further.

---

---
url: /fetch/intro.md
description: >-
  KosmoJS automatically derives fully-typed fetch clients with runtime
  validation for every API route. End-to-end type safety from frontend to
  backend with validation schemas and URL utilities.
---

When you define an API route with typed parameters, payloads, and responses,
KosmoJS derives a corresponding fetch client - automatically, as part of the same build step.

The result is a fully-typed client that mirrors your route definition exactly.
Parameters, payload shape, response type - all derived from the same source.
Change your API, and the client updates with it. No manual sync required.

## What Gets Derived

Each route's client module exports:

🔹 **HTTP method functions** - `GET`, `POST`, `PUT`, etc., accepting parameters and payloads
typed to match your route definition and returning typed response promises.
[Details ›](/fetch/start)

🔹 **`path` and `href` utilities** - construct relative or absolute URLs with proper
parameter substitution and optional query string support.
[Details ›](/fetch/utilities)

🔹 **`validationSchemas`** - the same schemas used for server-side validation,
exposed for client-side form validation with `check`, `errors`, `errorMessage`,
`errorSummary`, and `validate` methods.
[Details ›](/fetch/validation)

## Using the Client

Import the fetch map and pick the client for your route by path:

```ts [pages/example/index.tsx]
import fetchClients from "_/fetch";

const response = await fetchClients["users/[id]"].GET([123]);
```

Clients land in the `lib` directory alongside other derived artifacts
(validation routines, OpenAPI spec). Everything is updated automatically in the background
as you modify routes during development.

## Isomorphic Clients

The same client works in both CSR and SSR - identical code, no server functions or RPC layer to define.
In the browser it issues a normal same-origin request; during SSR it dispatches to the matched API route in-process,
with no network layer and no round-trip latency.

[Isomorphic clients ›](/fetch/isomorphic-clients)

---

---
url: /fetch/start.md
description: >-
  Import and use KosmoJS fetch clients with full TypeScript typing. Access
  routes directly or through a centralized map with automatic parameter and
  payload validation.
---

The fetch index exports a map of route paths to their clients:

```ts [pages/example/index.tsx]
import fetchClients from "_/fetch";

const response = await fetchClients["users/[id]"].GET([123]);
```

## Method Signatures

Each client exposes methods for the HTTP verbs your route handles.
The signature reflects your route definition directly:

* First argument is a parameter array, in path order
* Second argument is the payload, if your handler defines one

Given this route:

```ts [api/users/[id]/index.ts]
export default defineRoute<"users/[id]", [number]>(({ GET }) => [
  GET<{
    query: { name?: string },
    response: [200, "json", { id: number; name: string; email: string }],
  }>(async (ctx) => { /* ... */ }),
]);
```

The client expects a number parameter and an optional payload:

```ts [pages/example/index.tsx]
const useFetch = fetchClients["users/[id]"];

const response = await useFetch.GET([123]);
const response = await useFetch.GET([123], { query: { name: "John" } });
// response is typed as { id: number; name: string; email: string }
```

## Routes Without Parameters or Payloads

No parameters, no array:

```ts
const response = await fetchClients["users"].GET();
```

If there is a payload to send without params, just use an empty array for params:

```ts
const response = await fetchClients["users"].GET([], {
  query: { filter: "active", page: 1 }
});
```

If the route defines no payload type (or `never`), the second argument is not required.
The client adapts to exactly what your API expects - passing the wrong shape is a type error.

## The Same Call in CSR and SSR

The call above needs no variant for the server. In the browser it issues a same-origin network request;
during SSR it dispatches to the API route in-process:

```ts [pages/example/index.tsx]
// identical in a client component and in an SSR loader
const response = await fetchClients["users/[id]"].GET([123]);
```

Nothing to configure - no separate server-side client, no base URL for the in-process path.
[Isomorphic clients ›](/fetch/isomorphic-clients)

---

---
url: /fetch/integration.md
description: >-
  Integrate KosmoJS fetch clients with SolidJS query/createAsync, React, Vue and
  Svelte useLoaderData, and MDX hooks. Type safety flows through all framework
  abstractions.
---

The fetch client returns standard promises, so it fits naturally into whatever async pattern your framework uses.

### The Same Call in CSR and SSR - React

```tsx
// React: pages/users/[id]/index.tsx
import { useLoaderData } from "react-router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

// React Router passes { params, request } into the loader; read params the
// native way and pass them to the client as an array
export const loader = ({ params }) => GET([params.id]);

export default function UserProfile() {
  const user = useLoaderData();
  return <div>{user.name}</div>;
}
```

### The Same Call in CSR and SSR - Solid

```tsx
// Solid: pages/users/[id]/index.tsx
import { Suspense } from "solid-js";
import { createAsync, query, useParams } from "@solidjs/router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

// wrap the fetch in query() so preload and createAsync share one cache key -
// both call getUser with the same arg and the result is fetched once
const getUser = query((id: string) => GET([id]), "user");

// SolidJS Router calls preload on navigation intent; read params from its arg
export const preload = ({ params }) => getUser(params.id);

export default function UserProfile() {
  const params = useParams();
  const user = createAsync(() => getUser(params.id));
  return <Suspense>{user()?.name}</Suspense>;
}
```

### The Same Call in CSR and SSR - Vue

```vue
<!-- Vue: pages/users/[id]/index.vue -->
<script lang="ts">
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

// the loader is a module-level export, so it lives in a plain <script> block -
// <script setup> compiles to setup() and cannot hold ES exports
export const loader = ({ params }) => GET([params.id]);
</script>

<script setup lang="ts">
import { useLoaderData } from "_/use";

const user = useLoaderData();
</script>

<template>
  <div>{{ user.name }}</div>
</template>
```

### The Same Call in CSR and SSR - Svelte

```svelte
<!-- Svelte: pages/users/[id]/index.svelte -->
<script module lang="ts">
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

// the loader lives in the module <script> block; the instance <script> can't hold ES exports
export const loader = ({ params }) => GET([params.id]);
</script>

<script lang="ts">
import { useLoaderData } from "_/use";

const user = useLoaderData();
</script>

<div>{user.name}</div>
```

### The Same Call in CSR and SSR - MDX

```mdx
// MDX: pages/users/[id]/index.mdx
import fetchClients from "_/fetch";
import { useLoaderData } from "_/use";

const { GET } = fetchClients["users/[id]"];
export const loader = ({ params }) => GET([params.id]);

export const user = () => useLoaderData();

export const User = () => {
  return <div>{user()?.name}</div>;
};

<User />
```

### The Same Call in CSR and SSR (cont.)

Types flow through these abstractions - loaders, resources, hooks, and components automatically
know the response shape from your API definition.

KosmoJS only owns the envelope - the typed fetch client and how requests cross the wire.
Everything above it is the framework's own model: Solid's `query`/`createAsync`, React Router's
`loader` and `useLoaderData`, Vue's `useLoaderData`, Svelte's `useLoaderData`, MDX's `useLoaderData` -
each reads through its native patterns, with no proprietary abstraction layered on top.

The client is just a typed function that takes the params array you build and returns a promise; where and how
you call it is entirely the framework's.

## These Integrations Work Under SSR Too

The client returns standard promises, so nothing above changes when the page is server-rendered.

What matters is **when** the fetch fires: loaders and preloaded resources run during the SSR render,
so they take the in-process path and their result is reused on hydration rather than refetched.

A fetch in `useEffect` / `onMounted` does not run during SSR - it fetches in the browser after hydration, like a plain CSR app.

[Isomorphic clients ›](/fetch/isomorphic-clients)

## Suspense Is Your Responsibility

Solid's `createAsync` (like `createResource`) suspends: it reports its pending
state to the nearest `<Suspense>` boundary and propagates errors to the nearest
`<ErrorBoundary>`. KosmoJS does not provide either for you - the seeded
`App` boilerplate renders its children directly, deliberately not wrapping the
app in `<Suspense>`, because one app-wide boundary is an anti-pattern: any
pending fetch anywhere collapses the whole page to a single fallback and
unrelated async work shares one loading state.

Scope the boundary to the data component or a sensible subtree yourself:

```tsx [SolidJS]
import { Suspense } from "solid-js";
import { createAsync, useParams } from "@solidjs/router";

export default function UserProfile() {
  const params = useParams();
  const user = createAsync(() => getUser(params.id));

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <div>{user()?.name}</div>
    </Suspense>
  );
}
```

React's `loader`/`useLoaderData` resolves before render and does not suspend,
so it needs no boundary unless you reach for `React.lazy` or a promise-throwing `use()`.
The same holds for Vue, Svelte, and MDX loaders - they resolve before render, so only
Solid's `createAsync` needs a boundary in the common case.
Wrapping the whole app in one boundary does work if you accept the
tradeoff - it is your call, not a default KosmoJS makes for you. See
[Data Preloading](/frontend/data-preload#suspense-is-your-responsibility) for the
full breakdown.

---

---
url: /fetch/isomorphic-clients.md
description: >-
  One fetch client, two transports - a same-origin request in the browser and an
  in-process dispatch into your API during SSR. What decides which one runs,
  what the in-process path actually does, how hydration reuses the result, and
  what happens when an SSR fetch fails.
---

A [fetch client](/fetch/intro) is one function you call the same way everywhere:

```ts
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

const user = await GET([123]); // a component, a loader, a preload - same call
```

What changes underneath is the **transport**:

| Where the call runs | Transport | What it costs |
|---|---|---|
| Browser | Global `fetch`, same-origin request | A normal HTTP request |
| Server, during SSR | Direct dispatch into the API app | A function call and an object - no socket, no localhost hop |

There is nothing to configure and no second client to import.

## Nothing is patched

Worth saying plainly, because "isomorphic fetch" elsewhere often means monkey-patching:
`globalThis.fetch` is never touched - not in the browser, not in Node.

The transport is a parameter of the fetch client, not a global that gets swapped:

* In the browser no transport is passed, so the client calls the platform's own fetch, pristine -
  with every redirect, credentials, caching, `AbortSignal` semantics, etc.
* On the server the client is constructed with a transport that speaks the same `Request -> Response` contract
  and hands the request to the API app instead of to the network.

## What decides which transport you get

Not a setting - **where and when the call happens**:

| Situation | Transport |
|---|---|
| `pnpm dev`, any folder | Network. The dev server is always [client-rendered](/dev-build-run/development-workflow#dev-renders-client-side), so there is no SSR pass to dispatch in |
| Production CSR folder | Network |
| SSR folder, call made **during render** - `loader`, `preload`, `createAsync` | In-process |
| SSR folder, call made **after hydration** - `useEffect`, `onMounted`, an event handler | Network |
| SSG build | In-process (see [below](#ssg-runs-the-same-path-at-build-time)) |

The rule underneath is simple: a fetch that fires while the server is rendering the page runs in the server's process;
a fetch that fires in the browser runs in the browser.

::: tip The dev server never shows you the in-process path
Dev is CSR, so the fetch you are watching in the network tab is the network one - even in a folder with SSR enabled.
Run [pnpm preview](/dev-build-run/production-preview) to exercise the real SSR path.
:::

## What the in-process path actually does

It is not a shortcut around your API. The SSR build bundles the backend in, and the client hands it a real `Request`:

* **Dispatched into the app instance** - `app.fetch(request)` for backends that expose it,
  an in-memory injection for the Node-style one. Either way the request goes through the whole chain:
  routing, [global](/backend/middleware) and [cascading](/backend/cascading-middleware) middleware,
  validation, your handler, [error handling](/backend/error-handling), response shaping.
* **With the page request's headers as defaults.** Cookies, `authorization`, tracing headers from the incoming request are forwarded,
  so an authenticated page renders authenticated data. Anything you set on the call itself wins over a forwarded value.
* **Following redirects in-process** - up to the five hops the fetch spec allows,
  including the `303` (and `301`/`302` from `POST`) rewrite to `GET`.
* **Without patching anything global.** Only fetch clients switch transports.
  Every other `fetch` in your app - a call to a third-party API, say - behaves exactly as it always did.

## Client-side validation is skipped under SSR

The client's pre-flight check exists to save a round trip. During SSR there is no round trip,
so it is disabled automatically and validation runs on the API endpoint only.
[Details ›](/fetch/validation)

## Hydration does not refetch

A request made during SSR is not repeated in the browser:

* **React and Solid** reuse the result through their built-in hydration.
* **Vue, Svelte and MDX** reuse it through the loader:
  the result is serialized into the page during SSR and read on the client before the loader would run.

So the common pattern - a loader that fetches, a component that renders it - costs exactly one call,
made in the server's process, and the browser starts from the finished result.

## When an SSR fetch fails

A failing call during SSR is not the same event as a failing call in the browser,
and it is worth knowing what the server does with it.

The in-process transport throws on a non-2xx response, and the error is also stashed on the request-scoped store -
because some frameworks swallow a rejected loader and render a partial tree anyway,
which would otherwise produce a half-rendered page with no visible error.

When the render finishes and that error is present, **the SSR output is discarded and the client shell is served instead**.
The browser then renders the page itself, where the failure reaches your own [error boundaries](/frontend/error-boundaries)
and surfaces the same way it would in a CSR app.

The server logs it:

```txt
WARN: SSR failed, fallback to CSR
SSRFetchError: /api/users/123: 500 [ Internal Server Error ]
```

That recovery needs an untouched response, so it applies to **string-rendered routes** - the default.
A [streamed route](/frontend/server-side-render#streaming-routes-do-not-recover) has already flushed its
status line and opening HTML by the time a fetch fails, so there is nothing left to replace:
streaming routes must handle fetch failures in the page itself.

The fallback is a deliberate trade - one consistent place to handle errors instead of server-side boundaries
that behave differently in every framework - but it has a practical consequence worth internalising:

::: warning A page that renders fine can still have lost its SSR
If a page silently arrives as an empty shell in production, check the server log before checking the client.
A single failing API call during render is enough to drop the whole page back to CSR,
and the page still works - it just stopped being server-rendered.
:::

To catch that without reading logs, give the renderers an [onError hook](/frontend/server-side-render#onerror-hook) -
it is called with the error that ended the render, so a lost SSR becomes an event in your monitoring rather than a line on stdout.
It reports only; the fallback happens either way.

This is a **serving-time** trade, and it applies to SSR only: at build time there is no visitor waiting,
so [SSG](#ssg-runs-the-same-path-at-build-time) writes nothing and fails the build instead.

Fetch clients always throw on failure, on both sides - but not the same object.
In the browser the thrown error carries the `response` and the parsed error `body`;
during SSR the transport throws first, with the route and status in its message.
And a `ValidationError` can only ever come from the browser, since the pre-flight check is not there under SSR.
[Details ›](/fetch/error-handling)

## SSG runs the same path at build time

[Static generation](/frontend/static-site-generation) is not a third mode.
The build starts a disposable SSR server, requests each route from it, and writes the returned HTML to disk -
so every fetch made during those renders takes the in-process path, inside the build.

Two consequences:

* **Your API runs during the build**, so the build needs the access production has -
  the real database, the CMS, whatever your routes read.
  That is a CI concern rather than a laptop one: the usual shape is a workflow that ships the sources to the production environment -
  or to a runner with the same credentials and network reach - and builds there,
  so every page is rendered against exactly the data production would have served.
* **A failed fetch costs you the whole build.** SSG does not fall back to a client shell:
  pre-rendering goes through every path, and if any of them failed it writes nothing and throws the collected errors.
  [Details ›](/frontend/static-site-generation#error-handling)

## What does not change

* **`path` and `href`** always produce URL strings - they are for links,
  redirects and external references, not requests, so there is nothing to swap.
  [Details ›](/fetch/utilities)
* **Types.** The same `ResponseT` and parameter types apply on both sides;
  nothing about the call signature depends on where it runs.
* **Your framework's data model.** Loaders, `createAsync`, `useLoaderData` -
  the client is a plain promise-returning function and the framework owns everything above it.
  [Details ›](/fetch/integration)

***

[Read more](/essentials/why-http) on why the boundary is there and why keeping it does not have to cost a round trip.

---

---
url: /fetch/validation.md
description: >-
  Automatic client-side validation with TypeBox schemas before network requests.
  Use check, errors, errorMessage methods for form validation with performance
  optimization patterns.
---

Fetch clients validate parameters and payload before making any network request -
using the exact same schemas as the server. Invalid data throws immediately, no round trip needed.

## Validation Schemas

Beyond automatic fetch validation, each client exposes `validationSchemas` for use directly in your UI -
ideal for real-time form feedback:

```ts
const { validationSchemas } = fetchClients["users"];

validationSchemas.params;      // parameter validation
validationSchemas.json.POST;   // JSON payload validation for POST
```

Each schema has four methods:

* **`check(data)`** - fast boolean check, safe to call on every keystroke
* **`errors(data)`** - returns `Array<ValidationErrorEntry>` with field-level detail; only call after `check` returns false
* **`errorMessage(data)`** - all errors as a single readable string
* **`errorSummary(data)`** - brief overview, e.g. `"2 validation errors found across 2 fields"`

`check` is cheap. `errors`, `errorMessage`, and `errorSummary` are heavier - gate them behind `check`.

## Field Paths

Nested field errors use arrow notation: `"customer -> address -> city"`.
Match them with word-boundary regex to avoid false positives:

```ts
const emailError = errors.find(({ path }) => /\bemail\b/.test(path));
```

## Per-Field Validation Performance

Schemas validate entire objects, not individual fields. This creates a subtle issue
when validating fields as users type: on a partially-filled form, `check` returns false
for missing required fields - not just the one you're testing - which triggers
unnecessary `errors()` calls on every keystroke.

The fix is to merge the actual field value into a fully-valid placeholder payload,
so `check` only fails when the field under test actually has a problem:

```ts
// Define a valid baseline - all required fields filled with values that pass all constraints.
// This is a one-time setup per form, not per keystroke.
const validPayload = { name: "Valid Name", email: "valid@example.com", age: 25 };

// On input event for "name" - override just that field
const payload = { ...validPayload, name: event.target.value };

if (!validationSchemas.json.POST.check(payload)) {
  const nameError = validationSchemas.json.POST.errors(payload).find(e => e.path === "name");
  // show nameError.message near the name field
}
```

Each field gets its own merge - `{ ...validPayload, email: event.target.value }` for email, and so on.
The placeholder values for other fields are never submitted anywhere,
they just keep `check` from firing false negatives.

Most forms don't need this. If you validate on submit rather than on input,
or your form has only a few fields, direct validation works fine.
It matters for complex forms with many required fields that validate in real time.

On submit, always validate the actual payload - not the merged one:

```ts
if (!validationSchemas.json.POST.check(actualPayload)) {
  const errors = validationSchemas.json.POST.errors(actualPayload);
  // surface all errors at once
  return;
}

await useFetch.POST([], actualPayload);
```

---

---
url: /fetch/type-safety.md
description: >-
  Fetch clients are fully typed - parameters, payload, and response all mirror
  the backend route. Access response types on the client with the ResponseT map.
---

The fetch client mirrors your backend route exactly.
Parameters, payload, and response are all typed from the same route definition -
change the route, and every call site updates with it.

Parameters and payload are checked the moment you call a method: the signature expects the
parameter array and payload shape your route declares, and passing the wrong thing is a
compile error. Nothing to import, nothing to annotate.

```ts [pages/example/index.tsx]
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

await GET([123]);                      // ✅ number param, as declared
await GET(["abc"]);                    // ❌ type error - param must be a number
await GET([123], { query: { q: 1 } }); // ❌ type error - `q` isn't in the query type
```

## Response Types

The response is fully typed at the call site too - awaiting `GET(...)` gives you a value typed
to that route's response, no annotation needed. So most of the time you never name the response
type at all; you just use the result.

What you occasionally need is the response type *out of band* - away from the call,
where there's no awaited result to infer from. Typing a Solid `createAsync` accessor,
a `useLoaderData()` result, a store, a component prop, or a shared helper are the common cases.

For those, KosmoJS derives a `ResponseT` map, exported from `_/fetch`.

`ResponseT` is keyed by route name, then request method, and resolves to the response **body**
type declared on that handler - the same type awaiting the method gives you, available as a
name you can reference anywhere.

Given this backend route:

```ts [api/users/[id]/index.ts]
export default defineRoute<"users/[id]", [number]>(({ GET }) => [
  GET<{
    query: { name?: string },
    response: [200, "json", { id: number; name: string; email: string }],
  }>(async (ctx) => { /* ... */ }),
]);
```

the response type is available on the client as:

```ts [pages/example/index.tsx]
import f, { type ResponseT } from "_/fetch";

ResponseT["users/[id]"]["GET"]; // { id: number; name: string; email: string }
```

::: tip Response types are opt-in
An entry exists in `ResponseT` only when the handler declares a `response`.
If a route defines no response type, it has no `ResponseT` entry -
just as it has no response validation. Declare a `response` to get both.
:::

### Without a `response`, the result is `unknown`

This is worth being explicit about, because it is the one case where the client is *not* typed for you.
A method whose handler declares no `response` returns `Promise<unknown>`:

```ts
// api/users/index.ts - no `response` declared
export default defineRoute<"users">(({ GET }) => [
  GET<{
    query: { page?: number },
    // no response schema // [!code hl]
  }>(async (ctx) => {
    // ...
  }),
]);
```

```ts
const users = await fetchClients["users"].GET();
users.length;  // ❌ 'users' is of type 'unknown'
```

`unknown` is deliberate rather than `any`: nothing was declared, so nothing is claimed,
and TypeScript makes you say what you expect instead of silently trusting it.

Declaring `response` on the handler is what fixes it - and it is the same one line that
turns on response validation and the OpenAPI response schema:

```ts
GET<{
  response: [200, "json", Array<User>] // [!code hl]
}>(async (ctx) => { /* ... */ })
```

```ts
const users = await fetchClients["users"].GET();
users.length;  // ✅ Array<User>
```

So the practical rule: **declare `response` on any handler whose result the frontend consumes.**
Params and payload are typed from the route definition regardless - it is only the return value that depends on `response`.

## Multiple Responses

A handler can declare a union of responses - different status codes returning different bodies.
`ResponseT` follows, collapsing to a union of the body types:

```ts [api/users/index.ts]
export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: NewUser,
    response:
      | [201, "json", User]             // created - full record
      | [202, "json", { queued: true }] // accepted for async processing
      | [409]                           // conflict, no body
  }>(async (ctx) => {
    // response must comply with one of the defined schemas
  }),
]);
```

Variants without a body - no third tuple element, like the bare `[409]` above -
contribute nothing to the type, so they drop out of the union:

```ts [pages/example/index.tsx]
import f, { type ResponseT } from "_/fetch";

ResponseT["users"]["POST"]; // User | { queued: true }
```

## Using Response Types

The out-of-band cases in practice - the hook that needs annotating at its untyped boundary -
and a shared helper naming the type once. `helpers.ts` is the same file for every framework.

### Using Response Types - React

```tsx
// React: pages/users/[id]/index.tsx
import { useLoaderData } from "react-router";
import f from "_/fetch";
import { formatUser, type User } from "./helpers";

const { GET } = f["users/[id]"];

export const loader = ({ params }) => GET([params.id]);

export default function UserProfile() {
  // useLoaderData is untyped at the boundary - annotate it with User type
  const user = useLoaderData<User>();
  return <div>{formatUser(user)}</div>;
}
```

### Using Response Types - Solid

```tsx
// Solid: pages/users/[id]/index.tsx
import { Show, Suspense } from "solid-js";
import { createAsync, query, useParams } from "@solidjs/router";
import f from "_/fetch";
import { formatUser, type User } from "./helpers";

const { GET } = f["users/[id]"];

// createAsync infers from the fetcher, so there is no boundary to annotate -
// User earns its keep on the query wrapper and on helper signatures
const getUser = query((id: string): Promise<User> => GET([id]), "user");

export const preload = ({ params }) => getUser(params.id);

export default function UserProfile() {
  const params = useParams();
  const user = createAsync(() => getUser(params.id));
  return (
    <Suspense>
      <Show when={user()}>{(u) => <div>{formatUser(u())}</div>}</Show>
    </Suspense>
  );
}
```

### Using Response Types - Vue

```vue
<!-- Vue: pages/users/[id]/index.vue -->
<script lang="ts">
import f from "_/fetch";

const { GET } = f["users/[id]"];

export const loader = ({ params }) => GET([params.id]);
</script>

<script setup lang="ts">
import { useLoaderData } from "_/use";
import { formatUser, type User } from "./helpers";

// useLoaderData takes the type argument - it returns User | undefined
const user = useLoaderData<User>();
</script>

<template>
  <div v-if="user">{{ formatUser(user) }}</div>
</template>
```

### Using Response Types - Svelte

```svelte
<!-- Svelte: pages/users/[id]/index.svelte -->
<script module lang="ts">
import f from "_/fetch";

const { GET } = f["users/[id]"];

export const loader = ({ params }) => GET([params.id]);
</script>

<script lang="ts">
import { useLoaderData } from "_/use";
import { formatUser, type User } from "./helpers";

// useLoaderData takes the type argument - it returns User | undefined
const user = useLoaderData<User>();
</script>

{#if user}
  <div>{formatUser(user)}</div>
{/if}
```

### Using Response Types - ./helpers.ts

```ts
// helpers.ts - framework-agnostic, identical in every folder
import type { ResponseT } from "_/fetch";

// name the type once, reuse it across components
export type User = ResponseT["users/[id]"]["GET"];

export const formatUser = (user: User) => {
  return `${user.name} [${user.email}]`;
}
```

### Using Response Types (cont.)

> MDX is absent here on purpose: `.mdx` is not TypeScript,
> so it has no type arguments and no type imports - an MDX page reads `useLoaderData()` untyped.

The type flows from the backend route through the client to wherever you consume it.
Change the route's `response` shape and every consumer - loaders, resources, helpers, props -
updates with it, surfacing mismatches at compile time instead of in production.

See [Fetch Client Integration](/fetch/integration) for the full set of framework patterns,
and [Response Validation](/validation/response) for declaring the `response` schema on the backend.

---

---
url: /fetch/error-handling.md
description: >-
  Fetch clients always throw on failure, so every failure is catchable.
  Distinguish ValidationError from network and server errors, and handle them
  with a try-catch or an error boundary at layout or app level.
---

Fetch clients always **throw on failure**.

Every failure - a validation error before the request, an HTTP error status, or a network/transport failure -
surfaces as a thrown error you can catch.

The return type stays the response type; a failed call never resolves to `undefined`,
and nothing is silently swallowed.

## Catching Errors

Wrap a call in `try/catch` and branch on the error type:

```ts [pages/example/index.tsx]
import fetchClients, { ValidationError } from "_/fetch";

const useFetch = fetchClients["users/[id]"];

try {
  const response = await useFetch.POST([userId], payload);
} catch (error) {
  if (error instanceof ValidationError) {
    // data didn't pass validation - no request was made
    console.error("Invalid data:", error.errorMessage);
  } else {
    // network error, or an HTTP error status from the server
    console.error("Request failed:", error);
  }
}
```

Three failure kinds reach that `catch`:

* **`ValidationError`** - parameters or payload failed client-side validation.
  Thrown before any network request, so nothing was sent.
  Carries the same structured detail as a server-side `ValidationError`,
  so you can surface field-level feedback immediately.
  [Details ›](/validation/error-handling)
* **HTTP error status** - the request was sent and the server responded with a non-2xx status.
  The thrown error carries the response and the parsed error body.
* **Network / transport failure** - the request never completed
  (DNS failure, connection refused, server down). The original transport error is thrown.

Every failure throws, so a plain `try/catch` around the call catches it. Nothing is swallowed.

## Error Boundaries

For anything beyond a single call, you don't want a `try/catch` per call -
you want one place that catches failures for a whole subtree.
That is an **error boundary**, mounted at layout level.

Because the client throws naturally, a fetch failure propagates like any other thrown error
and the nearest boundary catches it - so one boundary covers every call rendered beneath it.

Each framework provides its own boundary; mount it where you want failures to be caught
(usually the layout, so it wraps every page):

* **React** - an error boundary component (a class boundary or `react-error-boundary`).
* **Solid** - `<ErrorBoundary fallback={...}>` from `solid-js` around the layout's content.
* **Vue** - a wrapper using `onErrorCaptured`, or `app.config.errorHandler` globally.
* **Svelte** - `<svelte:boundary>` where available, otherwise handle at the data/load layer.
* **MDX** - renders through Preact, so it uses a Preact boundary (`useErrorBoundary` from `preact/hooks`).

A layout-level boundary for each framework:

### Error Boundaries - React

```tsx
// React: pages/dashboard/layout.tsx
import { ErrorBoundary } from "react-error-boundary";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <ErrorBoundary
      fallbackRender={({ error, resetErrorBoundary }) => (
        <div role="alert">
          <p>Something went wrong: {error.message}</p>
          <button onClick={resetErrorBoundary}>Try again</button>
        </div>
      )}
    >
      {children}
    </ErrorBoundary>
  );
}
```

### Error Boundaries - Solid

```tsx
// Solid: pages/dashboard/layout.tsx
import { ErrorBoundary, type ParentProps } from "solid-js";

export default function Layout(props: ParentProps) {
  return (
    <ErrorBoundary
      fallback={(error, reset) => (
        <div role="alert">
          <p>Something went wrong: {String(error.message ?? error)}</p>
          <button onClick={reset}>Try again</button>
        </div>
      )}
    >
      {props.children}
    </ErrorBoundary>
  );
}
```

### Error Boundaries - Vue

```vue
<!-- Vue: pages/dashboard/layout.vue -->
<script setup lang="ts">
import { ref, onErrorCaptured } from "vue";

const error = ref<Error | null>(null);

onErrorCaptured((err) => {
  error.value = err as Error;
  return false; // stop the error from propagating further
});

const reset = () => (error.value = null);
</script>

<template>
  <div v-if="error" role="alert">
    <p>Something went wrong: {{ error.message }}</p>
    <button @click="reset">Try again</button>
  </div>
  <slot v-else />
</template>
```

### Error Boundaries - Svelte

```svelte
<!-- Svelte: pages/dashboard/layout.svelte -->
<script lang="ts">
  let { children } = $props();
</script>

<svelte:boundary>
  {@render children()}

  {#snippet failed(error, reset)}
    <div role="alert">
      <p>Something went wrong: {error instanceof Error ? error.message : String(error)}</p>
      <button onclick={reset}>Try again</button>
    </div>
  {/snippet}
</svelte:boundary>
```

### Error Boundaries - MDX

```tsx
// MDX: pages/dashboard/layout.mdx
import { useErrorBoundary } from "preact/hooks";
import type { ComponentChildren } from "preact";

// MDX pages render through Preact; wrap {props.children} in your layout with this.
export default function ErrorBoundary(props: { children: ComponentChildren }) {
  const [error, reset] = useErrorBoundary();
  if (error) {
    return (
      <div role="alert">
        <p>Something went wrong: {error instanceof Error ? error.message : String(error)}</p>
        <button onClick={reset}>Try again</button>
      </div>
    );
  }
  return props.children;
}
```

### Error Boundaries (cont.)

A boundary catches errors thrown **during render**.
The two paths below are about getting each kind of failure onto that render path.

## Where Errors Surface

### TanStack Query

When a call runs inside `createQuery` / `useQuery`, TanStack catches the exception
and stores it in `query.error` - it does **not** throw during render by default, so no boundary fires.

Read `query.error` to handle it inline, or set `throwOnError` to escalate the error into the nearest boundary:

```ts
const query = createQuery(() => ({
  queryKey: ["user", id()],
  queryFn: () => fetchClients["users/[id]"].GET([id()]),
  throwOnError: true, // let the error boundary catch it instead of query.error
}));
```

Use `query.error` for inline, per-widget error UI; use `throwOnError` when a
failed load should hand off to the same layout-level boundary as everything else.

### Route loaders

A fetch call inside a route `loader` (React Router) or `preload` (Solid) reaches
the framework's own route-error channel:

* *React Router* surfaces the error through the route's `errorElement` (read it with `useRouteError`),
  rendered the same on the server render and after hydration.
* *Solid* surfaces it through the resource so a downstream `<ErrorBoundary>` under `<Suspense>` catches it.

Handle loader errors with the framework's route-level error UI, not with a `try/catch` inside the loader -
catching inside the loader hides the failure from the machinery designed to render it.

### Event handlers and mutations

A fetch call in a click or submit handler (including a TanStack mutation) runs outside render,
so a render boundary can't see it. Handle these with a local `try/catch` where the call is made,
and read `mutation.error` for mutation state.

## Defense in Depth

Client-side validation catches bad input before a request is sent,
but it is a UX convenience, not a security boundary.

The server always re-validates with the same schemas.
Treat client validation as fast feedback and the server's `ValidationError` response as the authority.
[Details ›](/fetch/validation)

---

---
url: /fetch/utilities.md
description: >-
  Build URLs with path and href utility functions that handle route parameters,
  query strings, and base URL configuration for navigation and external
  references.
---

Each fetch client exposes `path` and `href` for building URLs without making a request -
useful for navigation, `<a>` tags, or passing URLs to other services.

```ts [pages/example/index.tsx]
import fetchClients from "_/fetch";

const useFetch = fetchClients["users/[id]"];

useFetch.path([123]);
// -> "/api/users/123"

useFetch.path([123], { query: { include: "posts" } });
// -> "/api/users/123?include=posts"

useFetch.href("https://api.example.com", [123]);
// -> "https://api.example.com/api/users/123"

useFetch.href("https://api.example.com", [123], { query: { include: "posts" } });
// -> "https://api.example.com/api/users/123?include=posts"
```

Multiple parameters follow path order:

```ts
// route: posts/[userId]/comments/[commentId]
useFetch.path([456, 789]);
// -> "/api/posts/456/comments/789"
```

---

---
url: /dev-build-run/development-workflow.md
description: >-
  The KosmoJS dev server - HMR for client code, hot reload for the API, custom
  request routing, and resource cleanup with teardown handlers.
---

Each source folder serves a specific concern - marketing site, customer app, admin, etc.

Yet, development workflow is identical.

One dev server covers both sides of a folder. Client modules go through `Vite` with `HMR`;
API routes run in the same process and hot-reload on change.

There is no second command to start and no proxy to configure - requests are dispatched between the two by path.

## Starting the Dev Server

```sh
pnpm dev          # all source folders
pnpm dev front    # specific folder (front, admin, app, etc.)
```

Default port is `4556`, configured as `devPort` in `package.json`.

## What Happens on Start

1. Blank route and page files are seeded.
2. `Vite` compiles `api/app.ts`
3. Dev server starts, serving both client pages and your API routes
4. Requests are routed between Vite and your API by the folder's `backend.base`
5. File watchers monitor client modules and API files for changes

## Dev Renders Client-Side

`pnpm dev` is always `Vite` + `HMR` + client-side rendering,
even when folder has [SSR enabled](/frontend/server-side-render).

Server rendering happens in the production build,
so there is no server-rendered markup to look at while the dev server is running.
This catches people out coming from Next/Nuxt/TanStack Start,
where dev mirrors production rendering.

To see, test or debug anything server-rendered, run [kosmo preview](/dev-build-run/production-preview).
It serves the real production build and still reloads when you edit a file.

## Hot Reload vs HMR

The two sides of a source folder reload differently:

* **Client**: HMR - changed modules are patched in place, component state survives the edit.
  A component, a style, a page - the browser updates without a navigation.
* **API**: hot reload - on change, the API *program* restarts as a whole.
  There is no HMR for the backend, and reloads fire on more than route edits
  (config changes, shared types etc.)

A full restart means module-level state resets on every reload.
This is by design, not a limitation to work around:
a backend should be stateless, in development for fast reliable reloads
and in production so it can restart, scale, and run as multiple instances.

Keep anything that must survive a restart in a real store from day one -
the dev reload cycle is simply an early rehearsal of what production restarts do anyway.

What *does* need care across reloads is resources: open connections leak when
the program restarts around them. Close them in the [teardownHandler](#teardownhandler) hook.

## api/dev.ts

`api/dev.ts` is where the API side of the dev server is wired up.

It is re-evaluated on every relevant change: the previous setup is torn down, the file re-imported,
and the fresh handler serves the next request.

The three hooks below sit on that cycle.

### requestHandler

Returns the API request handler. Seeded default:

#### requestHandler - Hono

```ts
// Hono: api/dev.ts
import { getRequestListener } from "@hono/node-server";

import { devSetup } from "_/api:factory";
import app from "./app";

export default devSetup({
  requestHandler() {
    return getRequestListener(app.fetch);
  },
});
```

#### requestHandler - H3

```ts
// H3: api/dev.ts
import { toNodeHandler } from "h3/node";

import { devSetup } from "_/api:factory";
import app from "./app";

export default devSetup({
  requestHandler() {
    return toNodeHandler(app);
  },
});
```

#### requestHandler - Koa

```ts
// Koa: api/dev.ts
import { devSetup } from "_/api:factory";
import app from "./app";

export default devSetup({
  requestHandler() {
    return app.callback();
  },
});
```

#### requestHandler (cont.)

Override this for custom routing logic - WebSocket handling, multi-handler dispatch, etc.

### requestMatcher

Controls which requests go to your API vs Vite.

By default, requests are routed to the API handler if their URL starts with `backend.base`
or match any `backend.alias`.

Use this to implement custom heuristics for detecting API requests:

```ts
export default devSetup({
  requestHandler() {
    // ...
  },

  requestMatcher(req) {
    return req.url?.startsWith("/api") ||
           req.headers["x-api-request"] === "true";
  },
});
```

### teardownHandler

Runs before each API reload. Use it to close connections and release resources
that would otherwise leak across rebuilds:

```ts
let dbConnection;

export default devSetup({
  requestHandler() {
    // ...
  },

  async teardownHandler() {
    if (dbConnection) {
      await dbConnection.close();
      dbConnection = undefined;
    }
  },
});
```

Without cleanup, frequent rebuilds during active development can exhaust database connections.

::: tip
This hook is dev-only. In production the process exits and the OS reclaims everything;
it exists because a dev reload restarts the API *inside* a long-running process.
:::

## Inspecting API Routes

Routes can be inspected by providing `debug` option to `appFactory` in `api/app.ts`
(omitted by default, feel free to add it as needed):

```ts [api/app.ts]
import appFactory, { routes } from "_/api:factory";
import defaultErrorHandler from "./errors";

export default appFactory(
  routes,
  { debug: true }, // [!code ++]
  ({ app }) => {
  // ...
})
```

Example output:

```txt
      /api  [ index/index.ts ]
   methods: GET|HEAD
middleware: slot: @extendContext useExtendContext
            slot: validate:params useValidateParams
   handler: indexHandler
```

> Named middleware functions show by name; anonymous ones show their first line.
> Name your middleware functions - it makes this output significantly easier to read.

Individual `debug` properties are also available for targeted output:
`headline`, `methods`, `middleware`, `handler`.

Use this to display only headline:

```ts
export default appFactory(routes, { debug: "headline" }, ({ app }) => {
  // ...
})
```

If you rather need a custom logger, provide a function instead;
it will be provided with full debug object and the route itself.

```ts [api/app.ts]
export default appFactory(
  routes,
  {
    debug(log, route) {
      console.log(log.full);
    },
  },
  ({ app }) => {
    // ...
  },
);
```

The `log` signature:

```ts
{
  headline: string;
  methods: string;
  middleware: string;
  handler: string;
  full: string;
}
```

---

---
url: /dev-build-run/production-preview.md
description: >-
  Run the real KosmoJS production build locally with kosmo preview -
  server-rendered pages, bundled assets and production validation policy, still
  reloading on change.
---

The dev server is fast: `HMR`, client-side rendering. Most of the time that is what you want.

Sometimes it is not. Server-rendered markup, a bundling or tree-shaking problem,
asset hashing, the production validation policy - none of these exist until you build,
and none of them are visible from the dev server.

`preview` builds the project and runs
[dist/run.js](/dev-build-run/building-for-production#one-entry-point-for-the-whole-project) -
the same entry point production starts.

```sh
pnpm preview          # all source folders
pnpm preview front    # specific folder
```

Then it watches your sources, and on change it rebuilds. Production output, development loop.

Default port is `4558`, configured as `previewPort` in `package.json`.
It is deliberately separate from `devPort`, so preview and the dev server can run side
by side and you can compare the two in adjacent tabs.

## What You Are Actually Looking At

Everything comes from `dist/`. Nothing is transformed on the fly:

* **`SSR` folders** render on the server, so you see real server-rendered markup
  and can watch hydration happen.
* **`CSR` folders** are served as built static assets - hashed filenames, real
  chunk splitting, the `index.html` a static host would serve.
* **`API` folders** answer from the bundled backend,
  with [response validation off](/validation/response#development-vs-production) unless you
  asked for it per handler - the production policy, not the dev one.

If a page works in preview, it works when deployed. That is the whole point of the command:
the gap between "works locally" and "works in production" is where `SSR` bugs live.

## Hot Reload, Not HMR

A change triggers a full rebuild. There is no module patching and no preserved state.

This is not a missing feature. `HMR` works by replacing modules in a running graph,
which is exactly what a production bundle does not have.
Preview's contract is that the page in the browser is the page production serves;
patching it in place would break that contract, and a preview you cannot trust is worse than no preview.

A rebuild is a full production build, so expect seconds rather than the milliseconds of `HMR`.

Use the dev server for iteration and preview to verify.

::: tip
A failed rebuild leaves the previous build serving. The error is printed to the
terminal and the page keeps working, so a typo mid-edit does not take the
preview down.
:::

## When to Reach for It

* Checking server-rendered output, or debugging a hydration mismatch
* Confirming something works after bundling - dynamic imports, tree-shaking, anything that behaves differently unbundled
* Verifying assets, `base` paths and deep links resolve when the app is not at the root
* Sanity-checking a multi-folder layout end to end, since preview dispatches across folders exactly as `dist/run.js` will in production
* Reproducing a bug that only appears in a deployed build

For everyday work, keep using [pnpm dev](/dev-build-run/development-workflow).
Preview is the check before you ship.

---

---
url: /dev-build-run/building-for-production.md
description: >-
  Build and deploy KosmoJS applications to production - a single dist/run.js
  entry point across all source folders, plus per-folder servers for containers,
  serverless, and edge runtimes.
---

Each source folder builds independently, into its own subdirectory of `distDir` -
a client bundle, an API bundle when it has a backend, and an SSR bundle when SSR is on.

Alongside them the build writes one entry point that serves every folder at once,
so the simple deployment is a single process even when the project has several folders.

Splitting them across hosts stays available: each folder's bundles are runnable on their own.

## One Entry Point for the Whole Project

The build writes `dist/run.js` - a dispatcher over every source folder in the project.
Start it and the whole application is up:

```sh
node dist/run.js -p 4556
```

It routes incoming requests by path the same way the dev server does:
each folder's `frontend.base` and `backend.base` decide what it owns, longest prefix first.

A project with a marketing site at `/`, an admin app at `/admin` and an API-only folder at `/svc` is one process,
one port, no reverse proxy needed to glue the folders together.

Each folder is served as what it is. `SSR` folders render on the server;
`CSR` folders are served as static assets with a fallback to their `index.html`;
`API`-only folders answer on their `backend.base`.

You do not configure any of this - it follows from the folder's config.

`dist/run.js` is also what [kosmo preview](/dev-build-run/production-preview) runs,
so what you check locally is the same entry point production serve.

### Other Runtimes

`dist/run.js` is built on `node:http`, which `Bun` and `Deno` both implement,
so the same file runs unchanged on all three:

#### Other Runtimes - Node

```sh
node dist/run.js -p 4556
```

#### Other Runtimes - Bun

```sh
bun dist/run.js -p 4556
```

#### Other Runtimes - Deno

```sh
deno run -A dist/run.js -p 4556
```

#### Other Runtimes (cont.)

This is worth stressing because it is easy to assume otherwise:
nothing in the dispatcher is tied to a runtime-specific server API.

It is `node:http` all the way down, and the compatibility layers in `Bun` and `Deno` cover it.

## Running Folders Separately

`dist/run.js` is the simple path, not the only one.

Deploy folders separately when they have separate lifecycles -
a marketing site on a CDN and an API in a container, an admin app scaled independently of the public one,
or a folder that belongs in a different region entirely.

The per-folder servers below are what `dist/run.js` dispatches to internally,
so nothing changes about how a folder behaves when you run it on its own.

## Build Output

```txt
dist/
├── run.js               # dispatcher over every folder
└── front
    ├── api
    │   ├── app.js       # app instance
    │   └── server.js    # ready-to-use API server
    ├── client
    │   ├── assets/      # scripts, styles, images
    │   └── index.html
    └── ssr
        ├── app.js       # SSR app instance
        └── server.js    # SSR server bundle
```

The SSR output is only present when [SSR is enabled](/frontend/server-side-render).

## What to Deploy

When running folders separately, what you deploy depends on how the folder renders.
(With `dist/run.js` this is all handled for you - the section below matters when you split folders across hosts.)

### SSR folders - deploy the SSR server only.

The build bundles the folder's backend *into* the SSR server:
one process serves the client assets, renders pages, and answers API requests.

During server-side rendering, the [isomorphic fetch client](/fetch/isomorphic-clients) calls your route handlers in-process -
no network hop, no localhost round-trip.

After hydration, the same server answers the browser's API calls over HTTP
through a built-in gateway that routes everything under the folder's `backend.base` to the bundled backend.

```sh
node dist/front/ssr/server.js -p 4556   # pages + API, one process
```

There is nothing else to run - `dist/front/api/server.js` exists in the build output,
but deploying it alongside the SSR server would just duplicate the API.

### CSR folders - deploy the API server, serve the client statically.

The browser is the only consumer of your API here, and it reaches it over the network:
run `dist/front/api/server.js` and put `dist/front/client/` behind any static host or CDN.

### API-only folders (no frontend)

Deploy the API server, same as CSR minus the static assets.

## Running the API server

For CSR and API-only setups, the simplest deployment is running the bundled server directly:

### Running the API server - Node

```sh
node dist/front/api/server.js -p 4556
```

### Running the API server - Bun

```sh
bun dist/front/api/server.js -p 4556
```

### Running the API server - Deno

```sh
deno run -A dist/front/api/server.js -p 4556
```

### Running the API server (cont.)

For more control, use the app factory at `dist/*/api/app.js`.

**Hono / H3** - `app.fetch` is a Web Fetch API handler, so it plugs into each runtime's native server directly:

### Running the API server - Hono on Node

```js
import { createServer } from "node:http";
import { getRequestListener } from "@hono/node-server";

import app from "./dist/front/api/app.js";

createServer(getRequestListener(app.fetch)).listen(3000);
```

### Running the API server - H3 on Node

```js
import { createServer } from "node:http";
import { toNodeHandler } from "h3/node";

import app from "./dist/front/api/app.js";

createServer(toNodeHandler(app)).listen(3000);
```

### Running the API server - Deno

```ts
import app from "./dist/front/api/app.js";

Deno.serve({ port: 3000 }, app.fetch);
```

### Running the API server - Bun

```ts
import app from "./dist/front/api/app.js";

Bun.serve({ port: 3000, fetch: app.fetch });
```

### Running the API server (cont.)

**Koa** - `app.callback()` is a Node.js `(IncomingMessage, ServerResponse)` handler.
Deno and Bun support it via their `node:http` compat layer, not via their native serve APIs:

```js [Koa on Node / Bun / Deno ~vscode-icons:file-type-js~]
import { createServer } from "node:http";

import app from "./dist/front/api/app.js";

createServer(app.callback()).listen(3000);
```

Or use `app.listen()` directly for Node only support:

```js [Koa on Node ~vscode-icons:file-type-js~]
import app from "./dist/front/api/app.js";

app.listen(3000);
```

---

---
url: /openapi.md
description: >-
  Automatically derive OpenAPI 3.1 specifications from KosmoJS API routes.
  Analyzes route structure, TypeScript types, and validation schemas to produce
  standards-compliant documentation.
---

KosmoJS derives an `OpenAPI 3.1` specification directly from your route definitions.
Route structure, `TypeScript` types, `VRefine` constraints, parameters, responses -
all reflected in the spec automatically. No manual schema authoring, no annotation layers.

## Enable OpenAPI

Simply add it to your source folder's `kosmo.config.ts`:

```ts
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  backend: {
    stack: "hono",
    base: "/api",
    openapi: { // [!code ++:6]
      outfile: "openapi.json",
      openapi: "3.1.0",
      info: { title: "My API", version: "1.0.0" },
      servers: [{ url: "https://api.example.com/api" }],
    },
  },
});
```

## Configuration

`backend.openapi` is the one block whose options are mandatory.
For how it sits alongside the rest of the folder config, see the [configuration reference](/essentials/config#backend-openapi).

### Required Options

**`outfile`** - Path where the spec is written, relative to your `kosmo.config.ts`.

**`openapi`** - OpenAPI version. Use `"3.1.0"` or any `3.1.x` version.

**`info`** - API metadata:

* `title` (required) - Name of your API
* `version` (required) - API version, use semantic versioning

**`servers`** - Array of server objects:

* `url` (required) - URL the API is served from, including the `backend.base` prefix.
  Paths in the spec are relative to this, so getting it wrong is the usual cause of a spec whose endpoints 404 -
  see [Server URLs and Route Paths](#server-urls-and-route-paths)
* `description` (optional) - Human-readable label

### Optional Info Properties

**`summary`** - One-line summary

**`description`** - Detailed description, supports markdown

**`termsOfService`** - URL to terms of service

**`contact`** - `name`, `url`, `email`

**`license`** - `name` (required), `identifier` (SPDX), `url`

### Complete Example

```typescript
const openapiConfig = {
  outfile: "openapi.json",
  openapi: "3.1.0",
  info: {
    title: "My SaaS API",
    version: "2.1.0",
    summary: "RESTful API for My SaaS Platform",
    description: `
# API Documentation
This API provides access to all platform features including
user management, billing, and analytics.`,
    termsOfService: "https://myapp.com/terms",
    contact: {
      name: "API Support",
      url: "https://myapp.com/support",
      email: "api@myapp.com",
    },
    license: {
      name: "Apache 2.0",
      url: "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
  },
  // this folder has backend.base "/api", so the dev server carries that prefix -
  // in production the API is deployed at the root of its own host and carries none.
  servers: [
    { url: "http://localhost:4556/api", description: "Development server" },
    { url: "https://staging-api.myapp.com", description: "Staging environment" },
    { url: "https://api.myapp.com", description: "Production server" },
  ],
};
```

### Server URLs and Route Paths

Paths in the spec are route names, exactly as they appear under `api/`.
A route at `api/users/[id]/index.ts` becomes `/users/{id}`,
and the `index` route becomes `/` - neither carries the folder's
[backend.base](/essentials/config#backend-base-required).

That is deliberate, not an omission. In `OpenAPI`, paths are relative to `servers`,
and the prefix an API answers on is a deployment decision rather than a property of the route.

The same backend may sit behind `/api` in development,
at the root of a dedicated host in production, and under `/v2/api` behind a gateway -
so the prefix belongs to the server entry, and the paths stay the same in all three.

This is why `servers` is mandatory: it is the only place the prefix is recorded.
Give each entry the full prefix, origin plus `backend.base`:

```ts
// folder with backend.base "/api"
servers: [
  { url: "http://localhost:4556/api", description: "Development server" },
  // deployed at the root of its own host - no prefix to add
  { url: "https://api.myapp.com", description: "Production server" },
];
```

```ts
// folder with backend.base "/admin/api"
servers: [
  { url: "http://localhost:4556/admin/api", description: "Development server" },
  { url: "https://myapp.com/admin/api", description: "Production server" },
];
```

A client built from the spec resolves `/users/{id}` against whichever server
it is pointed at, requesting `http://localhost:4556/api/users/42` in development
and `https://api.myapp.com/users/42` in production - one spec, no per-environment
rebuilds.

::: tip
If **Try it out** in `Swagger UI` returns `404`, check the server URL first.
A missing `backend.base` prefix is the usual cause.
:::

## Derived Specification

The output is a complete `OpenAPI 3.1` document covering:

* **Paths** - all routes with HTTP methods, parameters, request bodies, and responses
* **Schemas** - type definitions extracted from your `TypeScript` types and validation schemas
* **Parameters** - path, query, and header parameters with types and constraints
* **Request Bodies** - payload schemas for POST, PUT, and PATCH endpoints
* **Responses** - response schemas with status codes and content types
* **Validation Rules** - `VRefine` constraints appear as JSON Schema keywords

### Path Variations for Optional Parameters

OpenAPI requires all path parameters to be mandatory,
so routes with optional parameters produce multiple paths.

For a route at `users/[id]/posts/{postId}/index.ts`, the spec contains:

* `/users/{id}/posts/{postId}` - full path with optional parameter present
* `/users/{id}/posts` - path without optional parameter

Both reference the same handlers and schemas.

### Live Updates

The spec is recomputed automatically whenever you modify route definitions, types, or validation schemas.
This happens in the background alongside validation and fetch derivation -
no manual rebuild step required.

Serve the spec with any standard tooling:
[Swagger UI](https://swagger.io/tools/swagger-ui/),
[Redoc](https://github.com/Redocly/redoc),
or [Stoplight Elements](https://stoplight.io/open-source/elements).

---

---
url: /faq.md
description: Frequently asked questions about KosmoJS for developers and LLM agents
---

**KosmoJS FAQ**

### Getting Started & Project Setup

#### What is KosmoJS and what problem does it solve?

A composable meta-framework for organizing multiple apps in a scalable project.

It avoids the friction of microservices (drifting shared types, separate CI/deploy),
monorepos (workspace/package/build-cache overhead and a `packages/shared` dumping ground),
and DIY glue (hand-rolled scripts that become load-bearing).

Instead it uses a Vite-inspired "source folders" approach: the structure of a monorepo,
the simplicity of a single project, and the independence of separate apps -
without the overhead of any of them.

You keep control of backend, frontend, state, styling, database, and deploy target;
KosmoJS owns routing conventions, the validation pipeline, middleware composition,
dev workflow, and build orchestration.
[Details ›](/about)

#### Is KosmoJS a runtime, a bundler, or a framework?

Rather a meta-framework built on top of Vite. There is no proprietary runtime, no custom bundler,
and no framework lock-in - every layer (Vite, Hono/H3/Koa, React/Vue/Solid/Svelte/MDX)
is a tool you can use, debug, and replace independently.
[Details ›](/about)

#### How do I create a new KosmoJS project?

Run `npm create kosmo demo` (or `pnpm create kosmo demo` / `yarn create kosmo demo`).
An interactive setup creates the project together with your first source folder,
asking only for the framework and backend - the folder defaults to `app` at base `/`.
Then `cd ./demo` and install dependencies.

Use `.` as the name to bootstrap into the current folder (e.g. a freshly cloned repo).
[Details ›](/start)

#### How do I create a project non-interactively?

Choose the framework and backend up front - when flags are present no prompts appear:
`npm create kosmo demo -- --frontend react --backend hono`
(pnpm and yarn forward flags without the extra `--`: `pnpm create kosmo demo --frontend ...`).

Required: `--frontend <name>` or `--no-frontend`, and `--backend <name>` or `--no-backend` -
the choice is always explicit; a missing flag is an error, never a silent default.

Optional: `--ssr`, `--ssg`, `--tsq`, `--overwrite`.
The first folder is always `app`, with pages at `/` and its API at `/api`.
[Full flag reference ›](/cli/create#cli-mode)

Use `.` as the project name to scaffold into the current folder: `npm create kosmo . -- --frontend ...`
[Details ›](/start)

#### How do I add a source folder?

Run `npm run folder` (or `pnpm folder` / `yarn folder`) - interactively, or with flags.
[Details ›](/cli/folder)

#### What am I prompted for when adding a source folder?

Frontend, backend, SSR, SSG (only if SSR is on) and TanStack Query.
Non-interactive: the name is a positional, plus
`--frontend solid|react|vue|svelte|mdx` or `--no-frontend`,
`--backend hono|h3|koa` or `--no-backend`, `--ssr`, `--ssg`, `--tsq`, `--overwrite`.
Frontend and backend each require a value or its negation flag,
and the name is required here - unlike at project creation, it has no default.
The folder gets pages at `/<name>` and its API at `/<name>/api`.
[Details ›](/cli/folder)

#### How do I create a backend-only (API) folder, or a frontend-only folder?

A source folder doesn't have to ship both sides - framework and backend are independent, and each is optional.
In interactive mode, choose `None (API-only folder)` in the framework select,
or `None (client-only folder)` in the backend select.

In non-interactive mode, pass the matching negation flag for the side you skip:

```sh
pnpm folder api  --backend hono --no-frontend   # backend-only, no UI
pnpm folder docs --frontend mdx  --no-backend   # frontend-only, no backend
```

The seeded `kosmo.config.ts` contains only the block that side needs.
[Details ›](/cli/folder)

#### Can I create a project without a source folder?

No - every project starts with its first source folder; omitting the name positional just falls back to the default (`app`, pages at `/`, API at `/api`).
A project without folders has nothing to serve or build - the source folder is the unit of everything in KosmoJS.
Add more folders any time with `npm run folder`.
[Details ›](/start)

#### Why install again after adding a source folder?

Adding a folder pulls in framework-specific dependencies that need to be installed.
[Details ›](/start)

#### How do I start the dev server and what's the default port?

`pnpm dev` (all folders) or `pnpm dev front` (one folder). Default port is `4556`.
[Details ›](/dev-build-run/development-workflow#starting-the-dev-server)

#### How do I change the dev port?

It's the `devPort` value in `package.json`.
[Details ›](/dev-build-run/development-workflow#starting-the-dev-server)

#### How does this compare to Next.js / Nuxt / SolidStart / tRPC / a hand-rolled Vite setup?

Unlike Next/Nuxt/SolidStart it doesn't choose your frontend or own your deploy model;
unlike tRPC it's route-based (not procedure-based) and also derives OpenAPI and runtime validators;
unlike a hand-rolled Vite setup it provides directory routing for both sides,
derived validation/clients, an isomorphic fetch client (in-process on the server
during SSR, no network hop), out-of-the-box SSR with an opt-in streaming render mode,
and multi-folder build orchestration without the DIY glue.
[Details ›](/features)

### Source Folders

#### What is a source folder?

A self-contained app inside the project with its own framework stack, base URL,
routing, middleware, layouts, config, and build output -
but sharing one `package.json`, one `node_modules`, one database layer, and one set of types.
Example layout:

* `src/app` (React + Hono, base `/`)
* `src/admin` (Vue + H3, base `/admin`)
* `src/marketing` (MDX, no backend, base `/`)

[Details ›](/features)

#### How is this different from a monorepo package / microservices / DIY glue?

Folders are not separate packages: no workspaces, no package boundaries,
no internal dependency graph, no publishing, no versioning, no workspace protocols.
You get monorepo-like structure and microservice-like independence with single-project simplicity.
[Details ›](/about)

#### Can different folders use different frameworks/backends at the same time?

Yes. Each folder picks its own backend (Hono/H3/Koa) and frontend (React/Vue/SolidJS/Svelte/MDX),
and they coexist in one project.
[Details ›](/features)

#### How do folders share types without publishing/versioning?

Import a type directly across folders through the reserved aliases - `@/*` for root-level
imports, `~/*` for source-folder imports, `_/*` for derived code. Change a database model
and every folder sees it immediately. No publishing, no workspace protocols.
[Details ›](/essentials/project-structure#path-mappings)

#### Can I build/deploy a single folder?

Yes - `pnpm build front` builds just that folder. Folders develop together as one project,
but can be built all at once or one at a time, and each build is a self-contained entity you
can deploy independently.
[Details ›](/dev-build-run/building-for-production)

#### How do I run/build all folders vs one?

`pnpm dev` / `pnpm build` for all; append a folder name (`pnpm dev front`, `pnpm build admin`) for one.
[Details ›](/dev-build-run/development-workflow#starting-the-dev-server)

#### Do routes/types leak between folders?

No - derived types and utilities are scoped per folder.
The admin dashboard's navigation types won't include the main app's routes, and vice versa.
[Details ›](/essentials/project-structure#path-mappings)

#### When should I split into separate folders?

One folder per distinct concern (main app, admin, marketing).
A useful rule for SSR vs CSR: deploy an SSR folder for marketing content
and a CSR folder for the app rather than mixing SSR/CSR within one folder.
[Details ›](/frontend/server-side-render#technical-considerations)

### Configuration

#### Where does configuration live, and is there a `vite.config.ts`?

Per source folder, in `src/<folder>/kosmo.config.ts` -
there is no project-wide kosmo config and **no separate `vite.config.ts`**.
Vite's `UserConfig` goes in `viteConfig`, on the `frontend` and `backend` blocks separately -
`plugins`, `resolve`, `css`, `define`, and the rest.
A few Vite keys are excluded because KosmoJS derives them from the folder layout:
`root`, `base`, `cacheDir`, `mode`, `builder`, `future`, `legacy`.
Project-wide settings (`distDir`, `devPort`, `previewPort`, scripts) live in the root `package.json`.
[Details ›](/essentials/config)

#### What options does a source folder config take?

Three optional blocks: `frontend`, `backend`, `validation`.
`frontend` takes `stack`, `base` (required), `fetch`, `ssr`, `ssg`, `tanstack`, `templates` and `viteConfig`.
`backend` takes `stack`, `base` (required), `openapi`, `alias`, `templates` and `viteConfig`.
`stack` is either a name or `{ name, plugin }`, where `plugin` is a Vite plugin instance you construct.
`validation` is `true` or a TypeBox options object.
[Details ›](/essentials/config#the-shape)

#### What do I import in `kosmo.config.ts`?

`defineConfig` from `@kosmojs/dev`, and nothing else.
You name a `stack` and flip features on; `defineConfig` assembles the generators for you.
`@kosmojs/dev` also exports the generators themselves, for the `generator` escape hatch
that swaps a built-in generator for your own on any block.
[Details ›](/essentials/config#bringing-your-own-generator)

#### What runs, and in what order?

Fixed, and independent of how you write the config:
`core -> backend -> validation -> openapi -> fetch -> frontend -> ssr -> ssg`.
`coreGenerator` always runs first and is never listed.
`validation` and `openapi` only apply when a `backend` is present,
and `fetch` only produces clients when there are backend routes to derive them from.
[Details ›](/essentials/config#bringing-your-own-generator)

#### Should I add my stack's Vite plugin to `viteConfig.plugins`?

No - it reaches Vite through `stack`, so listing it in `viteConfig.plugins` runs the transform twice.
To configure it, construct it yourself and pass it as `plugin`:
`frontend: { stack: { name: "react", plugin: react({ jsxRuntime: "classic" }) }, base: "/" }`.
With a bare name KosmoJS builds the plugin with the arguments the current command needs;
an instance you pass is used as written, so set those yourself.
[Details ›](/essentials/config#frontend-stack-required)

#### How do I change the `/api` prefix, and where does it come from?

It is `backend.base` in the folder's `kosmo.config.ts`, and it is a **full path** -
not a suffix joined onto `frontend.base`. A route's URL is `backend.base` + route name,
so `backend: { base: "/admin/api" }` serves `users/[id]` at `/admin/api/users/:id`.
The `api/` **directory** name never appears in the URL - it only separates server routes from `pages/` on disk.
[Details ›](/essentials/config#backend-base-required)

#### Can I rename `VRefine`?

Yes - set `refineTypeName` inside the `validation` options object.
It stays globally available and import-free under whatever name you choose.
[Details ›](/essentials/config#validation)

#### How do I map an extra URL onto an existing route?

The `alias` option in the `backend` block: `backend: { alias: { "/feed.xml": "rss" } }`.
Keys are absolute URLs, not prefixed by the router's base; if a key has dynamic segments,
their names must match the target route's parameters exactly or the request 404s.
[Details ›](/backend/aliases)

### Directory-Based Routing

#### How does routing map files to URLs?

Folder names become path segments; `index` files define the endpoint or component:

* `api/users/[id]/index.ts` maps to `/api/users/:id`
* `pages/users/[id]/index.tsx` maps to `/users/:id`.

No separate routing config - your file structure is your route definition.
[Details ›](/routing/intro#how-it-works)

#### Why directory-based instead of file-based?

Clarity at scale: only `index.ts` is a route handler; every other file in the folder
is an obviously-colocated helper. File-based routing leaves `schema.ts`/`auth.ts`/`utils.ts` ambiguous -
route or helper? Directory-based removes that ambiguity.
The only cost is creating a folder even when it holds just `index.ts`.
[Details ›](/routing/rationale)

#### Why must every route be a folder with an `index` file, even the root?

Consistency - no special cases. The base route uses a folder named `index`
(`pages/index/index.tsx` -> `/`).
[Details ›](/routing/intro#how-it-works)

#### How do nested routes work?

Nest folders. `api/users/[id]/posts/index.ts` -> `/api/users/:id/posts`,
as deep as your domain requires, each level colocating its own helpers, types,
and tests without affecting siblings. Nesting also composes vertically: layouts wrap
nested pages, and middleware cascades down the tree, so a parent segment's layout and
middleware apply to everything beneath it.
[Details ›](/routing/intro#nested-routes)

#### Why the parallel `api/` and `pages/` structure?

Intentional - a page and its corresponding API endpoint are always one folder apart and easy to find.
[Details ›](/routing/intro#how-it-works)

#### How do I create an API route?

Create a folder under `api/` with an `index.ts` file - the folder path becomes the URL
and KosmoJS seeds starter code automatically. For example, `api/products/index.ts`
exposes `/api/products`, and `api/products/[id]/index.ts` exposes `/api/products/:id`.
Inside, default-export a `defineRoute` that returns method handlers,
then replace the seeded placeholder with real logic and visit the URL
(e.g. `http://localhost:4556/api/products`).
[Details ›](/routing/intro#route-file-requirements)

#### How do I create a page?

Create a matching folder under `pages/` with an `index` component file for your framework -
`pages/products/index.tsx` (React/SolidJS), `.vue` (Vue), `.svelte` (Svelte), or `.mdx` (MDX) - and it becomes `/products`.
KosmoJS seeds a placeholder component you replace with your own;
the parallel `api/` and `pages/` trees mean a page and its endpoint are always one folder apart.
The two sides are coupled by usage, not by name - you pick the names on each end freely. The
docs mirror api and page names purely for consistency; matching them is a convention, not a
requirement.
Pages typically read data through the fetch client (`fetchClients["products"].GET()`).
[Details ›](/routing/intro#route-file-requirements)

#### What does the `_/` prefix and `_/api` map to?

`_/` maps to `lib/` (derived code). `_/api` resolves to `lib/<folder>/api.ts`,
where `<folder>` is your source-folder name.
[Details ›](/essentials/project-structure#path-mappings)

#### What do `@/*`, `~/*`, `_/*` mean?

Reserved path mappings:

* `@/*` root-level imports
* `~/*` source-folder imports,
* `_/*` derived-code imports.

Don't reuse these prefixes for your own aliases.
[Details ›](/tutorial)

### Route Parameters

#### What are the three parameter types?

* `[id]` required (exactly one segment)
* `{id}` optional (one segment or nothing)
* `{...path}` splat (any number of segments).

Same syntax for API routes and pages.
[Details ›](/routing/params)

#### How do I read a splat parameter?

Matched segments come back as an array - for `/docs/guides/deployment/production`,
`ctx.validated.params.path` is `["guides", "deployment", "production"]`.
Useful for doc sites, file browsers, arbitrarily nested paths.
[Details ›](/routing/params#splat-parameters)

#### Why can't an optional param precede a required one?

It creates ambiguity; `users/{optional}/[required]` is invalid.
Optional params must not be followed by required ones (`users/{section}/{subsection}` is fine).
[Details ›](/routing/params#optional-parameters)

#### Why am I getting an unexpected 404 with an optional param before a static segment?

With `properties/{city}/filters`, visiting `/properties/filters` makes the router match
`{city}="filters"` and then expect another `/filters` segment that isn't there - 404.
Fix it by adding an explicit static route (`properties/filters/index.tsx`), which takes priority.
[Details ›](/routing/params#watch-out-for-ambiguous-paths)

#### When does a static route win over a dynamic one?

Always - static routes take priority over dynamic ones.
[Details ›](/routing/params#watch-out-for-ambiguous-paths)

#### How does a sibling `index` make `[id]` effectively optional?

A parent `index` provides a fallback to render, so `careers/index.tsx` + `careers/[jobId]/index.tsx`
makes `[jobId]` effectively optional. `{jobId}` communicates that intent more clearly;
both notations work identically here.
[Details ›](/routing/params#required-vs-optional-a-subtlety)

#### How do mixed segments work?

Static text + params in one segment: `[category].html`, `[id]-[data].json`, `[name].[ext]`.
The folder is named with the mixed segment and `index.ts` lives inside it like any other route.
[Details ›](/routing/params#mixed-segments)

#### Which frontends support mixed segments?

* *Backend*
  * Hono and H3: partial support with caveats.
  * Koa: full support.
* *Frontend*:
  * Vue, Svelte, and MDX: full support.
  * React Router: `.ext` suffix only.
  * SolidJS: not supported.

Prefer simple segments for frontend routes and keep mixed segments to the API side where support is complete.
[Details ›](/routing/params#mixed-segments)

#### What is power syntax?

Raw `path-to-regexp v8` patterns passed through directly.
The rule: any param name containing non-alphanumeric characters is treated as a raw pattern.
Examples: `book{-:id}-info`, `locale{-:lang{-:country}}`, `api/{v:version}/users`.

**Koa is the only backend with full support**: Hono matches but renames the params (`_0abc`),
H3 won't match at all, and no frontend supports it - keep power syntax on the API side, on Koa.
Read the path-to-regexp docs before using it in production.
[Details ›](/routing/params#power-syntax)

#### How do I make an optional static part (e.g. an optional `.html`)?

e.g. `products/{:category.html}` - matches `/products` and `/products/electronics.html`
but not `/products/electronics`.
[Details ›](/routing/params#power-syntax)

#### Does KosmoJS run its own path-to-regexp routing under the hood?

No - path-to-regexp is used only at build time to parse your directory structure into route definitions.
At runtime, those parsed routes are registered with each framework's native router
exactly as you would register them by hand, so you keep the framework's full native routing:
Hono's high-performance router on the backend, and React Router / Solid Router / Vue Router
(with their nested layouts) on the frontend.
KosmoJS is the chassis, not the engine - the engine is whichever framework you chose.
[Details ›](/routing/intro#native-routing-under-the-hood)

### Seeded Boilerplate

#### What happens when I create a route file?

KosmoJS detects it and writes appropriate boilerplate -
an API route (`defineRoute`) vs a page component, matched to your framework.
You rarely write the skeleton by hand.
[Details ›](/backend/custom-templates)

#### Why doesn't my editor show seeded content immediately?

Some editors load it instantly; others need a brief unfocus/refocus of the file.
[Details ›](/backend/custom-templates)

#### Why avoid anonymous arrow functions as default exports?

A page's default export should be a named function (`export default function Page() {...}`) -
an anonymous arrow can break Vite's HMR.
[Details ›](/frontend/custom-templates)

#### How do I override the default seeded template?

Pass `templates` in the `frontend` or `backend` block of `kosmo.config.ts`, keyed by route-name glob pattern.
Each value is either a template string or a function of the route returning one.
Both blocks accept it:
[Custom Page Templates ›](/frontend/custom-templates#configuration) ·
[Custom Route Templates ›](/backend/custom-templates#configuration)

#### Which seeded files can templates override?

Route `index` files and nothing else - `pages/**/index.*` on the frontend,
`api/**/index.ts` on the backend.
Every other seeded file gets the built-in minimal boilerplate to start from.
[Frontend ›](/frontend/custom-templates) ·
[Backend ›](/backend/custom-templates)

#### Why didn't my new template change an existing route file?

Boilerplate is written **only into blank files** - work you have already done is never overwritten,
so changing a template does not retroactively rewrite existing routes.
Empty the file and it will be filled again.
[Details ›](/backend/custom-templates)

#### How does glob matching work for templates?

`*` matches exactly one nesting level, `**` matches any depth,
and an exact string targets a single route. Templates work with all parameter types
(`users/[id]`, `products/{category}`, `docs/{...path}`, combined).
[Details ›](/frontend/custom-templates#pattern-syntax)

#### When multiple template patterns match, which wins?

The first matching pattern, in the order the keys are written - so order them
most-specific first (`landing/home` before `landing/*` before `**`).
Caveat: JavaScript hoists integer-like keys to the front of an object, so a pattern such
as `"2024/**"` matches before anything written above it; prefix it with `./` to keep your
order. The same applies to `renderMode`, which uses the same resolver.
[Details ›](/frontend/custom-templates#resolution-priority)

#### How do templates help with CRUD seeding?

Define one backend route template with the standard boilerplate - method handlers,
validation targets, a declared `response` - and every seeded `api/**/index.ts` across
many tables starts with the right structure instead of the skeleton being retyped N times.
[Details ›](/backend/custom-templates#seeding-crud-endpoints)

### Backend

#### Why does `defineRoute` repeat the route path I'm already in?

Because TypeScript can't see the file system. Routing itself never uses the string -
the URL comes from the file's location. The name is the key into the derived `RouteMap`,
and that lookup is what types `ctx.validated.params` and the cascading `use.ts` context
for that route. Since no runtime argument carries it, nothing can be inferred, so the
type argument is required - and the seeded boilerplate already contains it.
It cannot drift silently: `R extends keyof RouteMap`, so a stale name after a folder
rename is a compile error.
[Details ›](/backend/intro#the-route-name-type-argument)

#### How do I define an endpoint?

Default-export a `defineRoute` definition; the factory receives HTTP method builders and `use`,
and returns an array of handlers. Import `defineRoute` from `_/api`.
[Details ›](/backend/intro#defining-endpoints)

#### Can I define multiple methods in one file?

Yes - return `GET`, `POST`, `PUT`, `DELETE`, etc. in the array.
[Details ›](/backend/intro#defining-endpoints)

#### Does handler order matter?

No - dispatch is by HTTP method. Undefined methods return `405 Method Not Allowed` automatically.
[Details ›](/backend/intro#defining-endpoints)

#### Which method builders exist?

`HEAD`, `OPTIONS`, `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.
[Details ›](/backend/intro#defining-endpoints)

#### What happens to a HEAD request if I only define GET?

It is served by the `GET` handler, validated against its schemas, with the body dropped per the HTTP spec -
`HEAD` is the one method that doesn't fall through to `405`.
Define `HEAD` explicitly only when you want to override that - except on Hono, where you cannot:
its router ignores any `HEAD` handler you define and fallback to `GET` handler.
[Details ›](/backend/intro#defining-endpoints)

#### Why method-based routing?

In KosmoJS a single route folder owns one URL, and inside it you declare a handler per HTTP method -
`GET`, `POST`, `PUT`, and so on - rather than branching on `ctx.method` or splitting verbs across files.

This keeps everything about one resource in one place:
the read, create, update, and delete logic for `/users/[id]` all live in that folder's `index.ts`,
each as its own typed handler with its own validation and middleware.

Because dispatch is by method, the handlers are declarative and order-independent -
you list them in any order and the framework routes to the right one,
returning `405 Method Not Allowed` automatically for verbs you didn't define.

The style draws on Sinatra (2007), the Ruby framework that pioneered defining routes as
`get "/path" do ... end` blocks - the same idea of a verb mapping straight to a handler,
brought into a typed, directory-based structure.
[Details ›](/backend/intro#defining-endpoints)

#### Is there HMR for the API? Why does my in-memory state reset in dev?

No HMR on backend.

On the frontend, Vite patches modules in place;
on the backend, changes trigger a hot reload: the whole program restarts, and module-level state resets with it.

That's normal for a backend - it should be stateless so it can restart and scale.

Keep persistent state in a real store (a database, even a local SQLite file),
and close connections in `teardownHandler` so they don't leak across reloads.
[Details ›](/dev-build-run/development-workflow#hot-reload-vs-hmr)

### Backend: Hono / H3 / Koa

#### Hono/H3/Koa - which should I pick, and when does it matter?

* *Hono*: Maximum performance, run unchanged across runtimes (Node, Deno, Bun, Workers), and prefer a clean, return‑based API.
* *H3*: Similar to Hono in performance and multi‑runtime support, but with a stronger focus on Web standards and framework‑agnostic design.
* *Koa*: Battle-tested, mature ecosystem, Node-focused. Great for traditional Node.js servers where you value stability and a large library ecosystem.

[Details ›](/backend/intro)

#### What's identical and what differs between Hono/H3/Koa implementation?

Identical: route organization, middleware patterns, validation,
the `use` API, slots, cascading middleware.
Different: the context API inside handlers (body, params, state, error model).
[Details ›](/backend/intro)

#### How do params differ in Hono vs H3 vs Koa?

Raw params: `ctx.req.param()` (Hono), `event.context.params` (H3), `ctx.params` (Koa) - all return untyped strings.

Always prefer `*.validated.params` - the validated, refined type (e.g., number) with runtime validation automatically enforced.
The validation logic is identical across all frameworks.
[Details ›](/backend/context#route-parameters)

#### How do I set the response in Hono/H3/Koa implementation?

The native way for every framework:

* *Hono*: `ctx.json(...)` / `ctx.text(...)` (return a Response‑like object)
* *H3*: Return the value directly - an object is serialized as JSON (application/json),
  a string is sent as plain text (text/plain). You can also return a Response for full control.
* *Koa*: `ctx.body = ...` (mutate the context)

All three frameworks support setting status codes and headers as well
(e.g., `ctx.res.status = 201` in Hono, `event.res.status = 201` in H3, `ctx.status = 201` in Koa).
[Details ›](/backend/intro)

#### How do the error models differ?

* *Hono*: `app.onError()` catches everything (`await next()` does not throw).
  It captures any error thrown in handlers; returns a `Response`.
* *H3*: Uses `app.use(onError(errorHandler))` as the global error handler.
  It captures any error thrown in handlers; returns a `Response`, plain object or string.
* *Koa*: Errors bubble up through `await next()`. Koa emits an `error` event (for logging),
  but doesn't send a response automatically. Use `app.on("error", errorHandler)` to react on `error` event.
  Use `try`/`catch` around `await next()` in middleware to set `ctx.status`/`ctx.body`.

[Details ›](/backend/error-handling)

### Backend: Context

#### What is `ctx.bodyparser`?

A unified parser API - `.json()`, `.form()`, `.raw()` - identical across frameworks.
Results are cached, so calling the same parser repeatedly doesn't re-parse.
[Details ›](/backend/context#unified-bodyparser)

#### Do I usually call bodyparser directly?

Rarely - defining a validation schema runs the appropriate parser automatically
and places the result in `ctx.validated`.
[Details ›](/backend/context#unified-bodyparser)

#### What is `ctx.metaparser`?

The same idea for request metadata - `.params()`, `.query()`, `.headers()`, `.cookies()`.
Synchronous, and cached like the body parsers.
`params()` and `query()` come back normalized - splats split into arrays, values coerced to your declared types -
while `headers()` and `cookies()` are plain parses.
[Details ›](/backend/context#unified-metaparser)

#### What is `ctx.validated`?

The validated, typed result for each target you defined:
`ctx.validated.json`, `.query`, `.headers`, `.cookies`, `.form`, `.raw`, `.params`.
[Details ›](/backend/context#validated-data-access)

#### How do I access normalized data before validation runs?

Through the parsers. The context is extended before any validator runs, so `ctx.metaparser`
and `ctx.bodyparser` are already on it while `ctx.validated` is still empty.
Useful in [edge middleware](/backend/edge-middleware)
and in a [custom validator](/backend/middleware#overriding-validation).
Both are cached, so reading there costs nothing: the validators and your handler reuse the same values,
and the request stream is read once.
[Details ›](/backend/context#unified-metaparser)

#### Is normalized the same as validated?

No. Normalizing splits splats and coerces types; it doesn't check anything.
Your refinements run in the validators, and only the checked results land in `ctx.validated`.
So `ctx.metaparser.query()` may hand you a number that your schema would still reject.
[Details ›](/backend/context#unified-metaparser)

#### Can I use the parsers in `api/app.ts`?

No - `api/app.ts` runs before the context is extended, so there is no
`ctx.metaparser`, no `ctx.bodyparser` and no `ctx.validated` yet.
Read the request through the framework's own API, or move the check into `api/use.ts`
under an `edge:` slot, which runs just after the context is extended.
[Details ›](/backend/middleware#app-middleware)

#### Do the raw params still work?

Yes - `ctx.req.param()` (Hono), `event.context.params` (H3), `ctx.params` (Koa) still return raw strings if you need them.
[Details ›](/backend/context#route-parameters)

### Backend: Middleware

#### How do I add route-level middleware?

Use the `use` builder inside `defineRoute`. By default middleware applies to all HTTP methods;
call `next()` to continue, skip it to short-circuit.
[Details ›](/backend/middleware#basic-usage)

#### Where does global middleware live?

`api/use.ts`, at the root of a source folder's `api/` directory.
Whatever it default-exports runs for **every route in that folder** - no imports, no registration.
It's seeded with the folder and is an ordinary file you edit; route templates never touch it.
Use it for route-wide concerns (request id, a blanket auth check, permission checks, audit logging);
anything narrower belongs in a subtree `use.ts` or the route's own `use`.
[Details ›](/backend/middleware)

#### Where does CORS go?

`api/app.ts`, as [app middleware](/backend/middleware#app-middleware).
Neither global nor edge middleware works for CORS - a preflight `OPTIONS` is answered before any route chain runs,
so anything composed per route never sees it and the browser rejects the request.
[Details ›](/backend/middleware#app-middleware)

#### How do I return 401 instead of 400 when a token is bad?

Give the auth middleware an `edge:` slot - `edge:auth`, say - and it runs ahead of validation,
so an unauthenticated request is rejected before any schema is consulted.
Declare it in `api/use.ts`, a cascading `use.ts` or the route itself;
the file decides reach, the slot decides position.
[Details ›](/backend/edge-middleware)

#### So, where do I add my auth?

Depends on whether any route needs to opt out.
Same rules everywhere - put it directly in `api/app.ts`: one middleware, no slots,
nothing downstream can replace it by accident, and it also covers unmatched URLs, preflights and `405`s.
Some routes authenticating differently - a signature-verifying webhook, a public health check -
use an `edge:` slot, so any route or subtree can substitute its own check.
[Details ›](/backend/edge-middleware#so-where-do-i-add-my-auth)

#### Can I have more than one edge middleware?

As many as you like - give each its own name. `edge:auth`, `edge:ratelimit`, and so on:
they run at the edge in declaration order, and each is its own slot, independently overridable.
[Details ›](/backend/edge-middleware#name-your-slots)

#### Do `edge:*` slots need a `UseSlots` declaration?

No. Every `edge:` prefixed name is reserved, like the validation slots - nothing to add to `api/env.d.ts`.
Typos are still caught, though: `edge-auth` is not a slot.
[Details ›](/backend/edge-middleware#name-your-slots)

#### What is the bare `edge` slot, and can I use it?

It holds the built-in middleware that extends the context -
the one that puts `ctx.metaparser` and `ctx.bodyparser` on it.
Claim `edge` and you replace that, so nothing downstream has those helpers and validators, middleware and handlers all break.
Always prefix your own: `edge:auth`, not `edge`.
[Details ›](/backend/edge-middleware#name-your-slots)

#### I put auth in `api/app.ts` and a route still declares `slot: "edge:auth"` - which one wins?

Both run. An `edge:auth` slot substitutes an `edge:auth` entry declared above it;
it can't replace anything in `api/app.ts`, because that layer isn't composed by KosmoJS at all.
The route ends up authenticating twice, by two different rules - pick either one.
[Details ›](/backend/edge-middleware#so-where-do-i-add-my-auth)

#### Is `api/use.ts` the same as Express's `app.use()`?

No - it runs **per route, not per request**. Global middleware is composed into each route's chain,
so a request matching no route never reaches it, and it never sees requests outside this folder's `backend.base`.
For work that must happen on every request regardless of routing,
use the framework's own app instance in `api/app.ts`, where `appFactory`'s callback hands you `{ app }`.
[Details ›](/backend/middleware)

#### Can a route override or skip global middleware?

Only if the global entry declares a `slot`. A route (or a cascading `use.ts`) declaring the same slot substitutes it -
and the replacement runs **in the global one's position** in the chain, so surrounding order is preserved.
A global middleware **without** a slot always runs and cannot be overridden or skipped, which is what you want for a security check.
[Details ›](/backend/middleware#slot-composition)

#### How does the onion model work?

Middleware runs in definition order going in, then unwinds in reverse after the handler.
Global `api/use.ts` runs first, then route-level `use`, then the handler, then back out.
[Details ›](/backend/middleware#execution-order-onion-model)

#### Why do `use` calls run before handlers regardless of array position?

This is intentional, not a quirk of how you order the array. `use` registers middleware
and the method builders (`GET`, `POST`, ...) register handlers;
the framework always runs the middleware chain first, then the matched handler -
so a `use` written after a handler in the array still runs before it.
If you need logic to run *after* the handler, put it after `await next()` inside a middleware:
code before `await next()` runs on the way in, code after it runs on the way back out (the onion model).
[Details ›](/backend/middleware#execution-order-onion-model)

#### How do I restrict middleware to specific methods?

Pass the `on` option to `use`, listing the methods the middleware should run for.
Handlers for other methods skip it:

```ts
use(async (ctx, next) => {
  // ...
  return next();
}, { on: ["POST", "PUT", "DELETE"] })
```

The same `on` option works in cascading `use.ts` files.
[Details ›](/backend/middleware#method-specific-middleware)

#### What are middleware slots?

Named positions in the middleware chain - middleware with the same slot name
replaces earlier middleware at that position, letting you override global defaults per-route
without bypassing everything else.
[Details ›](/backend/middleware#slot-composition)

#### How do I register a custom slot name?

Extend the `UseSlots` interface in `api/env.d.ts`, then use `{ slot: "yourName" }` anywhere.
[Details ›](/backend/middleware#slot-composition)

#### When I override via slot, does `on` inherit from what I'm replacing?

No - `on` doesn't inherit; set it explicitly if needed.
[Details ›](/backend/middleware#slot-composition)

#### How do `use.ts` files wrap subtrees?

Place `use.ts` in a folder and it automatically wraps all routes in that folder and its subfolders -
no imports or wiring. `api/users/use.ts` wraps everything under `/api/users`;
`api/users/account/use.ts` wraps only `/api/users/account`.
[Details ›](/backend/cascading-middleware#how-it-works)

#### What's the execution order across levels?

Global `api/use.ts` -> parent folder `use.ts` -> current folder `use.ts` -> route handler.
Parent always runs before child; children cannot skip parent middleware.
[Details ›](/backend/cascading-middleware#how-it-works)

#### What is `UseT`?

A type every `use.ts` in an `api/` subfolder exports (even when empty) describing what the middleware adds to context.
The global `api/use.ts` is the exception - it may export `UseT`, but the export is ignored there.
These are merged so every route underneath is typed automatically - no imports, no type args on `defineRoute`.
Inner definitions override outer ones, mirroring runtime.
[Details ›](/backend/cascading-middleware#type-safe-context-extension)

#### How do I extend `UseT` from a parent?

Import the parent's `UseT`, intersect it, and re-export -
avoiding duplicate definitions across the hierarchy.
[Details ›](/backend/cascading-middleware#type-safe-context-extension)

#### Why can some params be undefined in cascading middleware?

A `use.ts` runs for every route in its subtree, including ones that don't define a given param -
so the `id` param is present for `/users/[id]` but undefined for the `/users` route
under the same `use.ts`. That's expected, not a bug. Keep cascading middleware generic -
auth, logging, rate limiting; put param-specific logic in the route handler,
where the param is guaranteed to exist.
[Details ›](/backend/cascading-middleware#parameter-availability)

#### How do I implement auth / logging / rate limiting?

However your framework already does it - KosmoJS imposes nothing here and stays fully transparent.
Any Hono/H3/Koa middleware package works unchanged, wired the native way for your framework.
You can wire it directly in a route's `index.ts` via `use(...)`, or in an `api/` subfolder's `use.ts` to cascade it over a subtree.
Nothing is KosmoJS-specific about the middleware itself; it's plain Hono/H3/Koa.
[Details ›](/backend/cascading-middleware#common-use-cases)

### Backend: Error Handling

#### Where is the default error handler?

`api/errors.ts`, seeded per source folder - a regular file you can customize freely.
[Details ›](/backend/error-handling#default-error-handler)

#### How do I distinguish a ValidationError?

`error instanceof ValidationError` (from `@kosmojs/core/errors`) -> respond 400 with field detail;
otherwise use `error.statusCode || 500`.
[Details ›](/backend/error-handling#default-error-handler)

#### How do I do route-level error overrides?

The default error handler lives in `api/errors.ts`, the same across all frameworks.
The approach is uniform too: branch on the request path or context.
[Details ›](/backend/error-handling)

#### Why shouldn't I wrap handler logic in try-catch?

Let errors propagate to the central error handler instead of swallowing them per-route.
[Details ›](/backend/error-handling#let-handlers-fail)

### Validation

#### What is runtype validation?

TypeScript types are automatically converted to JSON Schema and validated at runtime -
no separate schema language, no schemas drifting out of sync.
One type definition is the source of truth for server validation,
client (fetch) validation, and the OpenAPI spec.
[Details ›](/validation/intro#understanding-runtype-validation)

#### How does one type give both compile-time and runtime safety?

The same definition that gives compile-time checking (autocomplete, refactor safety)
also produces the runtime validator that runs when real requests arrive -
closing the gap TypeScript can't cover at runtime.
[Details ›](/validation/intro#understanding-runtype-validation)

#### How are validators derived?

AST parsing (via ts-morph / TFusion) extracts types and traces referenced files;
AOT compilation produces high-performance validators in `lib` via TypeBox -
direct property checks, not a generic JSON Schema interpreter.
[Details ›](/validation/intro#how-derivation-works)

#### Why is double (client + server) validation a performance gain, not a cost?

Invalid requests are caught client-side before they leave the browser,
saving bandwidth/compute and giving users instant feedback;
server validation still runs for direct API calls.
[Details ›](/validation/intro#end-to-end-validation)

#### How do I refine params?

Pass a tuple as the second type argument to `defineRoute`;
each position maps to a param in path order (e.g. `<"users/[id]", [number]>`).
A request to `/api/users/abc` is rejected with 400 before the handler runs.
Refinements are positional, not name-based - renaming `[id]` to `[userId]` needs no change here.
[Details ›](/validation/params#params-refinements)

#### If URL params are strings, how does a `number` param validate?

KosmoJS coerces the value before validation: type a param as `number` and `"123"` becomes `123`,
while a non-numeric `"abc"` stays a string and fails the check with a clean 400.
So you write `number` (or a numeric `VRefine`) and read a real number from `ctx.validated.params`, no manual coercing.
[Details ›](/validation/params#params-refinements)

#### Why must the params tuple be written inline?

A pre-defined tuple *alias* loses the structural info needed to emit a schema.
Individual type aliases used *inside* the inline tuple are fine -
it's only extracting the whole tuple to a named type that breaks.
[Details ›](/validation/params#params-refinements)

#### What validation targets exist?

Metadata (any method): `query`, `headers`, `cookies`. Body (POST/PUT/PATCH): `json`, `form`, `raw`.
`form` covers both URL-encoded and multipart form data (so file uploads go here);
`raw` accepts plain text, binary data, `Buffer`, `ArrayBuffer`, or `Blob`.
[Details ›](/validation/payload#validation-targets)

#### Can validation targets hold numbers?

Only the `query` target will coerce numbers before validation:

```ts
GET<{ query: { page: number } }>((ctx) => {
  const { page } = ctx.validated.query // page is a number
});
```

`headers`/`cookies`/`form`/`raw` never coerce numbers.

::: warning will never pass validation
`POST<{ form: { age: number } }>`
:::

`json` carries numbers natively, no coercion needed.
[Details ›](/validation/payload#validation-targets)

#### Can validation targets hold booleans?

Only the `query` target will coerce booleans before validation - `"true"`/`"false"` become `true`/`false`:

```ts
GET<{ query: { draft?: boolean } }>((ctx) => {
  const { draft } = ctx.validated.query // draft is a boolean (or undefined)
});
```

`params` (path segments, where a boolean is meaningless), `headers`/`cookies`/`form`/`raw` never coerce booleans.

::: warning will never pass validation
`POST<{ form: { consented: boolean } }>`
:::

`json` carries booleans natively, no coercion needed.

For a non-`query` target, use a string union instead:

```ts
POST<{ form: { consented: "true" | "false" | "on" | "off" } }>
```

#### Why one body target but multiple metadata targets?

Body targets are mutually exclusive (one per handler - you can't have both `json` and `form`);
metadata targets can be combined freely. A body target on GET, or two body targets,
is flagged at dev time and the affected schema is disabled.
[Details ›](/validation/payload#validation-targets)

#### How do I handle file uploads?

Use the `form` body target on a POST/PUT/PATCH handler - it accepts multipart form data,
so the uploaded file and any accompanying text fields are validated together as one payload.
Type the file field alongside the metadata fields (e.g. `form: { file: ..., title: string }`),
and the parsed result is available on `ctx.validated.form` like any other validated body.
[Details ›](/validation/payload#validation-targets)

#### How do I validate responses, and why bother?

The `response` property as a positional tuple: `[status, contentType, Schema]`,
e.g. `[200, "json", User]`.
It validates before sending (catching handlers that return incomplete objects
or drifted DB/third-party shapes) and enables automatic OpenAPI derivation.
[Details ›](/validation/response)

#### Does response validation run in production?

Not by default: in production, response validation is disabled by default.
To enable, set `runtimeValidation: true` on the response target.
There is no global switch: each handler enables its own response validation.
[Details ›](/validation/response#development-vs-production)

#### Can I use referenced types and generics?

Fully supported - import shared types, use generic wrappers like `Payload<User>`.
Generics are resolved and every referenced type traced,
and rebuilds the schema when a shared type changes.
[Details ›](/validation/payload#referenced-types)

#### Inline object type vs `Payload<T>` for the `json` target - are they equivalent?

Yes. An inline literal (`json: { email: VRefine<string,{format:"email"}> }`)
and a named wrapper (`json: Payload<CreateUser>`) express the same thing -
the validated body schema. Use inline for one-off shapes and a named type to reuse a domain model.
[Details ›](/validation/payload#referenced-types)

#### What is VRefine?

It adds JSON Schema constraints to the target type - globally available, no import.
`VRefine<number, { minimum: 1, multipleOf: 1 }>`. The first argument is the base type,
the second is any valid JSON Schema validation keyword.
[Details ›](/validation/refine)

#### Which constraints apply where?

* Strings: `minLength`, `maxLength`, `pattern`, `format`
* Numbers: `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`
* Arrays: `minItems`, `maxItems`, `uniqueItems`.

The second VRefine argument accepts any valid JSON Schema validation keyword,
so the underlying keyword family is broader than the constraints listed here.
[Details ›](/validation/refine)

#### Why does `number` allow decimals, and how do I get integers?

Plain `number` permits floats. Use `multipleOf: 1` for true integers -
critical for DB IDs, where a float passes validation but gets rejected at the query level,
turning a clear validation error into a confusing DB error.
[Details ›](/validation/refine)

#### How do I validate emails / date-times / patterns?

`format: "email"`, `format: "date-time"`, or a `pattern` regex via VRefine.
[Details ›](/validation/refine)

#### What does a ValidationError expose?

`target` (which request part failed: `params`/`query`/`headers`/`cookies`/`json`/`form`/`raw`/`response`),
`errors` (array of `ValidationErrorEntry` with `keyword`/`path`/`message`/`params`/`code`),
`errorMessage` (all errors as one string), `errorSummary` (e.g. "2 validation errors found across 2 fields"),
`route`, and `data` (the data that failed).
[Details ›](/validation/error-handling#validationerror-properties)

#### How do I surface field-level form errors?

Map `error.errors` to `{path, message}` pairs; `target` tells you which request part failed.
Nested field paths use arrow notation (`customer -> address -> city`) -
match them with word-boundary regex to avoid false positives.
[Details ›](/validation/error-handling#validationerror-properties)

#### How do I set custom per-field error messages?

The second type argument to the handler accepts a per-target message set:
an `error` fallback plus `"error.fieldName"` overrides (dot notation for nested fields,
e.g. `"error.order.shipping.address.postalCode"`).
KosmoJS picks the most specific message; it appears in each entry's `message`.
[Details ›](/validation/error-handling#custom-error-messages)

#### Why must I avoid built-in type names?

Names like `Event`, `Response`, `Request`, `Error`, `Date`, `Partial`, `Record`, `Buffer`
are referenced as-is during type flattening, so the validator sees the built-in,
not your custom type - a silent runtime failure with no compile error.
Use a consistent `T` suffix/prefix (`EventT`, `TResponse`).
The full list is in the TFusion builtins reference.
[Details ›](/validation/naming-conventions#why-this-matters)

#### How do I skip runtime validation but keep types?

Per-target `runtimeValidation: false` in the second type argument (works for payload and response).
You then read the body via the bodyparser directly.

Param validation cannot be skipped - params are part of the URL structure.

For response targets the same flag is also the production opt-in:
response validation only runs in production when set to `true`.

Use sparingly: runtime validation is what catches mismatched DB responses,
unexpected payloads, and API drift.
[Details ›](/validation/skip-validation)

#### Can I replace the default validator with my own?

Yes - every target is middleware in a reserved slot, so claiming that slot runs your check instead:
`validate:params`, `validate:query`, `validate:headers`, `validate:cookies`,
`validate:json`, `validate:form`, `validate:raw`, `validate:response`.
Declare it globally in `api/use.ts`, in a cascading `use.ts` for a subtree,
or in the route itself for one endpoint. Reserved slots need no `UseSlots` declaration.
[Details ›](/backend/middleware#overriding-validation)

#### If I override one target, do the others still validate?

Yes - slots are per target. Overriding `validate:json` replaces the JSON validator and nothing else;
`ctx.validated.params`, `.query`, `.headers` and `.cookies` are still filled in by their own validators.
[Details ›](/backend/middleware#what-you-take-over)

#### What do I lose by overriding a validator?

That target's entry in `ctx.validated`. The built-in validator loads the data,
checks it and publishes the result; yours is only expected to check -
so `ctx.validated.json` stays unset and the handler reads the body itself.
Which costs nothing: `ctx.bodyparser.<target>()` and `ctx.metaparser.<target>()` are lazy loaded and cached,
so your validator and your handler can both call them and the request stream is read once either way.
[Details ›](/backend/middleware#what-you-take-over)

#### `runtimeValidation: false` or a custom validator - which do I want?

`runtimeValidation: false` turns checking off for that target and keeps the types.
A slotted validator keeps checking, on your terms - the way in for a body format no schema describes,
or a check that has to hit the database.
[Details ›](/backend/middleware#overriding-validation)

### Type Safety

#### What type arguments does defineRoute accept?

* RouteName (required)
* Params refinements tuple
* Types unique to this specific route
  * Variables and Bindings for Hono
  * Context for H3
  * State and Context for Koa

[Details ›](/backend/type-safety#typing-state-context)

#### How do I type Cloudflare bindings (e.g. D1) in Hono?

The 4th type argument (`{ DB: D1Database }`) for a single route,
or `DefaultBindings` in `api/env.d.ts` globally; read via `ctx.env.DB`.
[Details ›](/backend/type-safety#typing-state-context)

#### How do I add global context/state types?

Declare them in `api/env.d.ts` via module augmentation:

* `DefaultVariables`/`DefaultBindings` (Hono)
* `DefaultContext` (H3)
* `DefaultState`/`DefaultContext` (Koa)

[Details ›](/backend/type-safety#global-context-types-api-env-d-ts)

#### Can I relax TypeScript strictness, e.g. `exactOptionalPropertyTypes`?

Yes, per source folder - the folder's `tsconfig.json` (`src/<folder>/tsconfig.json`)
extends the derived base config, so anything you set in its `compilerOptions` wins:

```json [src/front/tsconfig.json]
{
  "extends": "../../lib/front/tsconfig.json",
  "compilerOptions": { // [!code ++:3]
    "exactOptionalPropertyTypes": false
  }
}
```

`exactOptionalPropertyTypes: true` is the deliberate default:
validated optional params round-trip exactly as declared (`status?: T` means *absent*, not `status: undefined`),
which most codebases coming from looser configs notice immediately.
Relaxing it - or any other strictness flag - is a per-folder choice and only affects that folder's typecheck.

`compilerOptions` is the safe thing to add. An `include` is not:
it replaces the base one rather than merging, and the base is what puts the folder,
its `lib/` output and the ambient declarations in scope.
[Details ›](/essentials/config#typescript-config)

#### How do I typecheck?

`pnpm typecheck` - the same shape as `dev` and `build`:
no arguments checks every source folder, folder names check just those (`pnpm typecheck admin front`).
It takes one extra argument the others do not: `.` for the project root.

Each folder is checked against its own `tsconfig.json` - that's where JSX and framework settings live.

Every selected tsconfig is checked even if an earlier one fails,
so a single run reports all of them rather than stopping at the first.
The command exits `1` if any of them reported errors, which makes it usable as a CI gate directly.

A full run also checks the project root, so code outside `src/` can be covered.
What it covers is up to you: the root `tsconfig.json` starts with only `./lib/*.d.ts` in its `include`,
so the run happens but has nothing of yours in scope until you add paths to that list.
The folders are checked separately rather than in one pass because each has its own path mappings -
one `tsc` over everything would resolve `_/` against the wrong folder.
[Details ›](/cli/typecheck)

#### How do I typecheck only the project root?

`pnpm typecheck .` meaning the project root rather than a source folder.

Naming folders drops the root, so `pnpm typecheck admin` checks that folder only.
`.` puts it back: on its own it checks the root and nothing else,
and alongside folder names it adds the root to them - `pnpm typecheck . admin` checks both.

Useful after touching a script or a shared package while `src/` is untouched.

The root's `tsconfig.json` decides what "the root" covers,
and out of the box that is nothing of yours - its `include` holds only `./lib/*.d.ts`.
Add the paths you want checked, keeping that entry: `include` replaces rather than merges with the config it extends,
so dropping it takes the ambient declarations in `lib/` out of scope.
[Details ›](/cli/typecheck#selective-typechecking)

### Fetch Clients

#### How are fetch clients derived?

Automatically for every API route, derived from the same type definitions -
change the API and the client updates, no manual sync.
Output lands in `lib` alongside validators and the OpenAPI spec.
[Details ›](/fetch/intro)

#### How do I call a client?

`import fetchClients from "_/fetch"`, then `fetchClients["users/[id]"].GET([123])`.
[Details ›](/fetch/start#method-signatures)

#### What's the method signature?

First argument is a params array in path order; second is the optional payload
(`{ query }`, `{ json }`, etc.). Every type is inferred from the route definition -
params, payload, and response alike.
[Details ›](/fetch/start#method-signatures)

#### How do I call a route with no params or no payload?

No params: call with no array (`fetchClients["users"].GET()`).
Payload but no params: pass `[]` for params (`GET([], { query: {...} })`).
If the route defines no payload, the second argument isn't required.
[Details ›](/fetch/start#routes-without-parameters-or-payloads)

#### Are requests validated before they leave the browser?

Yes - clients validate params and payload before any network request,
using the exact same TypeBox schemas as the server.
Invalid data throws immediately, no round trip.
[Details ›](/fetch/validation)

#### What are validationSchemas, and how do I use them in forms?

Each client exposes `validationSchemas` (`params`, `json.POST`, etc.) for real-time UI feedback.
Four methods: `check(data)` (cheap boolean, safe per keystroke), `errors(data)`
(field-level array, only after `check` fails), `errorMessage(data)` (one string),
`errorSummary(data)` (brief overview). Gate the heavy three behind `check`.
[Details ›](/fetch/validation#validation-schemas)

#### How do I do performant per-field validation as users type?

Schemas validate whole objects, so on a partially-filled form `check` fails
for *all* missing required fields, not just the one under test.
Fix: merge the field under test into a fully-valid placeholder payload
(`{ ...validPayload, name: e.target.value }`) so `check` only fails for that field.
On submit, always validate the real payload. Most forms don't need this -
it matters for complex forms validating in real time.
[Details ›](/fetch/validation#per-field-validation-performance)

#### How do I build URLs without making a request?

`path([123])` -> `/api/users/123`; `path([123], { query: { include: "posts" } })` adds a query string;
`href("https://api.example.com", [123])` builds an absolute URL.
Multiple params follow path order.
[Details ›](/fetch/utilities)

#### How do I distinguish ValidationError from network errors on the client?

`import fetchClients, { ValidationError } from "_/fetch"`;
`error instanceof ValidationError` means data failed validation and no request was made
(it carries `target`/`errors`/`errorMessage`/`errorSummary`);
anything else is a network or server error.
[Details ›](/fetch/error-handling#catching-errors)

#### How does it integrate with framework data patterns?

Clients return standard promises, so they drop into SolidJS `createResource`,
React Router `loader`/`useLoaderData`, TanStack Query `queryFn`, or a `useEffect`
hook. Types flow through these abstractions automatically. Render-time patterns
(loader, resource) also run during SSR in-process; a `useEffect` fetch only runs
on the client.
[Details ›](/fetch/integration)

#### How do I get a route's response type on the client?

You usually don't need to - awaiting a method already gives a typed result
(`const user = await fetchClients["users"].GET([123])` types `user` from the route's response).
For out-of-band typing - a `createAsync` accessor, a `useLoaderData()` result,
a prop, a shared helper - import `ResponseT` from `_/fetch`, keyed by route name then method:
`ResponseT["users"]["GET"]`.
[Details ›](/fetch/type-safety#response-types)

#### What does a fetch client return if the handler declares no `response`?

`Promise<unknown>`. Params and payload are always typed from the route definition,
but the **return** value is opt-in: declare `response` on the handler and you get the typed result,
response validation and the OpenAPI response schema together.
`unknown` rather than `any` is deliberate - nothing was declared, so nothing is claimed.
[Details ›](/fetch/type-safety#without-a-response-the-result-is-unknown)

#### Why is my route missing from `ResponseT`?

`ResponseT` is opt-in: an entry exists only for routes whose handler declares a `response` type.
A route with no `response` has no `ResponseT` entry - the same reason it has no response validation.
Add a `response` to the handler and the entry (and validation) appear together.
[Details ›](/fetch/type-safety#response-types)

#### What's the response type when a handler returns multiple responses?

A handler can declare a union of responses; `ResponseT` collapses to a union of their body types,
dropping any variant with no body (no third tuple element, like a bare `[409]`).
So `[201, "json", User] | [202, "json", { queued: true }] | [409]` yields `User | { queued: true }`.
[Details ›](/fetch/type-safety#multiple-responses)

### Frontend

#### Which frontend frameworks are supported?

React, SolidJS, Vue, Svelte, and MDX - directory routing bridges to each framework's
native router and reactive model.
[Details ›](/essentials/frameworks)

#### How do I add a frontend or backend to an existing folder?

Add the block to the folder's `kosmo.config.ts` - `frontend: { stack: "react", base: "/front" }` -
then restart the dev server.
The framework's Vite plugin is inserted for you - don't add the plugin yourself, or it runs twice.
[Details ›](/essentials/config#the-shape)

#### What `jsxImportSource` does each framework need?

React `"react"`, SolidJS `"solid-js"`, Vue `"vue"` (only when using JSX), MDX `"preact"`.
Mixing frameworks needs per-folder tsconfig - KosmoJS derives a `tsconfig.json`
per folder in `lib/` for your folder's `tsconfig.json` to extend from.
[Details ›](/frontend/intro#typescript-configuration)

#### What foundation files does a source folder get?

A root App component (your app shell), a router config (`routerFactory`),
and a client entry point (`entry/client`). SSR adds a server entry.
[Details ›](/frontend/intro#foundation-files)

#### What is routerFactory?

It wires your App + derived routes to the native router.
Its callback returns `clientRouter()` (browser navigation) and `serverRouter(url)` (SSR routing).
Derived routes are always wrapped inside your App, establishing the layout hierarchy,
and use the folder's `baseurl`.
[Details ›](/frontend/application#router-configuration)

#### What is renderFactory?

It orchestrates `mount()` (fresh client mount) vs `hydrate()` (hydrate SSR HTML),
choosing automatically via `__KOSMO_HYDRATION_BOOL__` global var.
Referenced from `index.html` through `entry/client`.
[Details ›](/frontend/application#application-entry)

#### Are page components lazy-loaded?

Yes - all page components are lazy-loaded by default and fetched on demand,
keeping the initial bundle small. The derived route shape differs slightly
per framework's router format.
[Details ›](/frontend/routing#lazy-loading)

### Layouts

#### How do layout files work?

A `layout` file in any `pages/` folder wraps every route in that folder and its subfolders;
nest layouts by nesting folders. No imports or config - the file system defines the hierarchy,
and child routes cannot escape parent layouts.
[Details ›](/frontend/layouts#define-a-layout)

#### What's the nested render order?

Outermost App -> each layout in path order -> the page. E.g. for `/dashboard/settings/profile`:
`App` -> `dashboard/layout` -> `dashboard/settings/layout` -> page.
[Details ›](/frontend/layouts#define-a-layout)

#### What's the recognized layout filename per framework, and is it case-sensitive?

`layout.tsx` (React/SolidJS), `layout.vue` (Vue), `layout.svelte` (Svelte), `layout.mdx` (MDX) - lowercase only.
Other casings are treated as regular components.
Each folder runs one framework and ignores other frameworks' files (a Vue folder ignores `.tsx`, etc.).
[Details ›](/frontend/layouts#layout-file-naming)

#### Why isn't my pages/layout.\* file loaded?

Layout files only apply inside route folders.
A layout outside a route folder is not picked up. `pages/layout.*` files are simply ignored.
If you look for a global layout that wraps every route, that's the `src/<folder>/app.*` file.
[Details ›](/frontend/layouts#global-layout-via-app-file)

#### What does the root app file wrap, and how is it different from a layout?

`src/<folder>/app.*` at the source-folder root wraps every route -
the place for truly global concerns (auth checks, analytics, error boundaries).
A `layout` file only works inside a route folder, wrapping the whole subtree.
Place it outside a route folder and it does nothing.
[Details ›](/frontend/layouts#global-layout-via-app-file)

#### How does each framework render the child route?

React `<Outlet/>`, Vue `<RouterView/>`, SolidJS and MDX `props.children`, Svelte `{@render children()}`.
[Details ›](/frontend/layouts#layout-implementation)

#### How do I load data in a layout?

Layouts are route-level, so a `layout.tsx` uses the same loader/preload a page does.
React (`loader` + `useLoaderData`), Solid (`preload` + `query`/`createAsync`),
Vue, Svelte, and MDX (all `loader` + `useLoaderData`) all load
at the layout level, fetching shared data once for everything beneath it.
For Vue, Svelte, and MDX a layout passes its path-qualified name to `useLoaderData`
(e.g. `useLoaderData("dashboard/layout")`) to read its own data rather than the
page's; React and Solid scope per route automatically.
[Details ›](/frontend/layouts#data-loading-in-layouts)

### Navigation (typed Link)

#### How does the typed Link component work?

Just import it from `~/components/Link.{tsx,vue,svelte}`.
The `to` prop takes a typed tuple `[routeName, ...params]` (e.g. `["users/[id]", 123]`), plus an optional `query` prop.
Typing the route name triggers IntelliSense; parameterized routes require their params.
[Details ›](/frontend/link-navigation#usage)

#### What's the refactor-safety benefit?

Renaming a route directory produces TypeScript errors at every `Link` referencing the old name -
turning refactors into an automated checklist.
[Details ›](/frontend/link-navigation#linkprops-type)

### Data Preload

#### How does route-level preloading work per framework?

`GET` here is a method off the fetch client for the route
(`const { GET } = fetchClients["users/data"]`) - exported under the name the framework's
router expects.

* React: `export { GET as loader }` - React Router calls it before render;
  `useLoaderData<ResponseT[...]>()` retrieves the typed result with no duplicate request
  (runs on load, hover, navigation).

* SolidJS: wrap the fetch in `query()` and export it as `preload` - called on
  hover/intent; `createAsync` calling the same `query`-wrapped function reuses the
  cached result. The raw client `GET` isn't cached, so the `query()` wrapper is
  what makes preload and `createAsync` share one fetch.

* Vue: `export const loader` in a plain `<script>` block (a `<script setup>`
  can't hold ES exports) - the router runs it before render, and the page reads
  the result with `useLoaderData()`.

* MDX: `export const loader` too - runs before render, and the page reads the
  result with the `useLoaderData()` hook (`props` stays yours).

[Details ›](/frontend/data-preload#page-integration)

#### Do I need a Suspense boundary for data fetching?

For SolidJS, yes - `createAsync` (like `createResource`) suspends, reporting pending state
to the nearest `<Suspense>` and errors to the nearest `<ErrorBoundary>`. KosmoJS
ships no boundary: the seeded `App` renders children directly, on purpose -
one app-wide `<Suspense>` is an anti-pattern (any pending fetch collapses the
whole page to a single fallback). Scope a boundary to the data component or a
subtree yourself. React, Vue, Svelte, and MDX loaders resolve before render and
don't suspend, so they need none unless you reach for something like `React.lazy`,
`use()`, or an async `<script setup>`.
Wrapping the whole app works if you accept the tradeoff - your call, not a default.
[Details ›](/frontend/data-preload#suspense-is-your-responsibility)

### MDX

#### When should I use MDX over React/Vue/Solid/Svelte?

MDX for content-primary folders (documentation, blogs, marketing) -
rendered to static HTML with Preact, minimal client JS by default.
React/Vue/Solid/Svelte for interactivity-primary folders (dashboards, client-side state, real-time forms).
Rule of thumb: primarily content with occasional interactivity -> MDX;
primarily interactive with occasional content -> a framework.
[Details ›](/frontend/mdx#when-to-use-mdx-vs-frameworks)

#### How do I write MDX pages?

`.mdx`/`.md` files in `pages/`, mixing markdown and JSX, with YAML frontmatter between `---` fences.
Import Preact components directly.
[Details ›](/frontend/mdx#writing-pages)

#### Is `_/use` available in my framework?

Only in **Vue, Svelte and MDX** folders. React and SolidJS folders get no `_/use` -
use `react-router` / `@solidjs/router` hooks instead.
Vue's `_/use` exports `useLoaderData` **only**; Svelte and MDX also export `useRoute`, `useParams`, `useParamsEntries`
and `useSearchParams`, and MDX adds `useFrontmatter`.
[Details ›](/frontend/hooks)

#### How do I access the current route inside a component?

Call the `useRoute()` hook from `_/use`. It returns the route `name`, the validated `params`,
and the page's `frontmatter` together, so a shared component (a breadcrumb, a title bar) can
read where it is without receiving props from the page. This is distinct from a framework's
own `useParams` - `useRoute()` also carries the route name and frontmatter, not just params.
[Details ›](/frontend/mdx#route-parameters)

#### How do I fetch data in MDX?

Export a `loader` function from the page. It runs before the page renders,
through the same fetch client used elsewhere in the project.
[Details ›](/frontend/mdx#data-fetching)

#### How do I access fetched data in MDX?

Read it with the `useLoaderData()` hook inside a component - `props` stays yours.
Because a hook must run during render, wrap the read in a small component
(`export const Msg = () => { const data = useLoaderData(); return <p>{data.msg}</p>; }`)
and place `<Msg />` in the markdown.
[Details ›](/frontend/mdx#data-fetching)

#### How do I use route name/params inside an MDX loader?

`loader` runs before the component tree exists, so hooks (`useParams()`, `useRoute()`) aren't available there -
they only work while Preact is actually rendering a component.
Instead, `loader` receives the resolved `Route` object as its argument, including `paramsEntries` -
a `[keys, values]` tuple in the same order the route declares its parameters,
ready to pass straight to a parametrized endpoint (`GET(params)`).
[Details ›](/frontend/mdx#loaders-with-route-parameters)

#### Why can't I write TypeScript in MDX?

MDX only supports plain JavaScript expressions.
Keep typed code (props, hooks, types) in `.tsx` files and import them into the MDX page.
[Details ›](/frontend/mdx#common-pitfalls)

#### How do I override markdown elements globally?

The component map in `components/mdx.ts` (applied through `MDXProvider`) -
override `h1`, `pre`, links, etc. for all pages. Individual pages can still import additional components.
[Details ›](/frontend/mdx#using-components)

#### How does frontmatter drive the head?

`title`, `description`, and a `head` array in frontmatter inject `<head>` content automatically -
the same convention as VitePress, no new syntax.
[Details ›](/frontend/mdx#frontmatter-head-injection)

#### What are the common MDX pitfalls?

No TypeScript in MDX (keep it in `.tsx`); hooks must be called inside components,
not at module scope (`export const x = useParams()` runs on import and fails);
`loader` can't use hooks either, since it runs before the tree exists - use the `Route`
argument instead; curly braces in prose are parsed as JSX - wrap in backticks;
layouts must be `.mdx` not `.md` (`.md` can't render `{props.children}`).
[Details ›](/frontend/mdx#common-pitfalls)

### SSR

#### Is SSR on by default?

No - folders default to client-side rendering (with Vite's dev server and HMR in dev). Enable
SSR when you create the folder (choose it in the interactive prompt, or pass `--ssr` in CLI mode),
or add it later by setting `frontend.ssr: true` in `kosmo.config.ts` and restarting dev.
[Details ›](/frontend/server-side-render#adding-ssr-support)

#### Does SSR run in dev?

No - in dev, Vite handles all requests with HMR and CSR for immediate feedback.
SSR activates exclusively in production builds.
(This commonly surprises Next/TanStack migrators who expect dev to mirror prod rendering.)
To see server-rendered output locally, run `pnpm preview`.
[Details ›](/frontend/server-side-render#development-experience)

#### renderToString vs renderToStream?

Both return `{ head, html }` - `renderToString` resolves `html` to a string (full page rendered before sending),
`renderToStream` resolves it to a `ReadableStream` (progressive flushing, better TTFB).
Framework folders implement both; which one runs per route is chosen by `renderMode`, not by precedence.
**Svelte and MDX are the exceptions** - both render to string only and implement no `renderToStream`.
[Details ›](/frontend/server-side-render#server-entry-point)

#### What do the render methods receive?

Both share the same first two arguments - the requested URL plus `SSROptions`:
`template` (client `index.html` with `<!--app-html-->` placeholder),
`manifest` (Vite's dependency graph),
and `assets` (SSR assets you inject manually, each offering `kind`/`tag`/`content`/`size`,
plus an optional `path` - content-only assets like inlined scripts have no URL).
`renderToStream` also receives the stream as a third argument for custom flushing control.
[Details ›](/frontend/server-side-render#render-factory-arguments)

#### Why must I inject SSR assets manually but not CSR assets?

CSR's index.html already carries the client asset tags.
For SSR, the server asks your renderer for `{ head, html }` and builds the document from them -
so composing assets into head is just your side of that handoff, not a Vite workaround.
[Details ›](/frontend/server-side-render#render-factory-arguments)

#### How does streaming work across runtimes?

`renderToStream` (imported from `_/entry/server`) returns a web-standard `ReadableStream`
for every framework, so streaming behaves the same on Node, Bun, and Deno. You return the
stream as `html`; the server handles writing it into the response. Enable it per route via
`renderMode`.
[Details ›](/frontend/server-side-render#stream-rendering)

#### How do I use a different render mode per route or group of routes?

`renderMode` in the `frontend.ssr` options controls string vs stream per route.
Every route defaults to `"string"`; set `"stream"` to stream all routes, or pass a map of glob patterns to opt in selectively.
When patterns overlap, the first match wins, so order them specific to general.
Streaming a route needs the folder's renderer to implement `renderToStream`;
**NOTE:** Svelte and MDX folders render to string only and don't accept the streaming mode.
[Details ›](/frontend/server-side-render#selecting-the-render-mode)

#### How do I build and run the SSR bundle, and on which runtimes?

`pnpm build` produces `dist/<folder>/ssr/server.js`, and `dist/run.js` if you'd rather run every folder from one entry.
Both work with `node`, `bun`, or `deno run -A` (`... -p 4556`); Unix sockets are supported across all three (`-s /tmp/app.sock`).
They use `node:http`, natively supported by all three runtimes.
[Details ›](/frontend/server-side-render#runtime)

#### Can I serve the SSR static assets so they don't hit the SSR server?

Yes. In-memory serving of `dist/<folder>/ssr/assets/` can't be turned off, but you can put a
reverse proxy or CDN in front to serve that folder directly, so asset requests never reach the
SSR process.
[Details ›](/frontend/server-side-render#static-asset-handling)

#### How do I deploy behind Nginx/Caddy?

Reverse-proxy to the SSR port (or a Unix socket). The SSR bundle includes the API, so it serves
API requests on the same port seamlessly - no separate API process needed alongside it.
[Details ›](/frontend/server-side-render#production-deployment)

#### What breaks during SSR?

Browser APIs (`window`, `document`, browser-only APIs) are unavailable server-side.
Coordinate async data so it's ready before render, plan state serialization for hydration,
and remember the hydration bundle still ships to clients (size still matters).
Use error boundaries so a server error doesn't terminate the process.
[Details ›](/frontend/server-side-render#technical-considerations)

#### How do I fetch data during SSR?

Use your framework's render-time data path - a `loader` (React, Vue, Svelte, MDX), a
`preload` (Solid), or a Solid `createResource`/Suspense resource - and call the
fetch client inside it. During
SSR the client dispatches to the API route in-process (the API server is bundled into the SSR
bundle), so there's no network hop, just the full validation/handler chain. A fetch in
`useEffect`/`onMounted` won't run on the server - those fire only after hydration.
[Details ›](/fetch/isomorphic-clients)

#### What happens if a fetch fails during SSR?

The SSR output is discarded and the client shell is served instead,
so the page re-renders in the browser where your own error boundaries handle the failure.
Server-side boundaries behave too differently across frameworks to rely on.
The server logs `WARN: SSR failed, fallback to CSR` along with the error.

This recovery needs an untouched response, so it covers **string-rendered** routes (the default).
A streamed route has already flushed its shell and cannot be replaced - it must handle fetch failures in the page itself.

To see these without watching logs, pass an [onError hook](/frontend/server-side-render#onerror-hook) to the renderers.

The page still works; it just isn't server-rendered any more.
If a page unexpectedly arrives as an empty shell in production, check the server log before the client.

All of this is about serving a live request. SSG has no such fallback: nobody is waiting on a build, so a page that fails there fails the build.
[Details ›](/frontend/static-site-generation#error-handling)

#### How do I log or report SSR render errors?

Both `renderToString` and `renderToStream` accept an [onError hook](/frontend/server-side-render#onerror-hook) in `entry/server.ts`,
called with the error that ended the render. Use it to log, count, trace or alert.

It reports only - it cannot change the response or the markup. A string-rendered route still falls back to CSR,
and a streamed route's shell is still on the wire.
Don't throw from it, and keep it cheap: it runs on the request path.
It also fires during SSG pre-rendering, inside the build.
[Details ›](/frontend/server-side-render#onerror-hook)

#### Does client-side validation run during SSR?

No - it's disabled automatically. The pre-flight check exists to avoid a round trip,
and there is no round trip during SSR, so validation runs on the API endpoint only.
[Details ›](/fetch/isomorphic-clients#client-side-validation-is-skipped-under-ssr)

### SSG

#### What is SSG, and when do I want it over SSR?

SSG renders pages to static HTML **at build time**, so the result deploys to a CDN or any static host with no running server.
Reach for it when the content is known at build time - docs, blogs, marketing, changelogs.
Use SSR instead when a page depends on the request (a signed-in user, live data, anything per-visitor).
[Details ›](/frontend/static-site-generation)

#### How do I enable SSG?

Choose it when creating the source folder (the interactive prompt asks, or pass `--ssg`),
or set `frontend.ssg: true` in an existing folder's `kosmo.config.ts`.

It requires **SSR enabled** on that folder - pages are rendered at build time by the folder's own SSR server -
which is why the creation prompt only offers SSG once you've chosen SSR.
[Details ›](/frontend/static-site-generation#adding-ssg-support)

#### How does SSG handle dynamic routes?

Static routes render automatically.
A dynamic route renders once per parameter set it declares through `staticParams` - one HTML file per entry.
A dynamic route **without** `staticParams` is skipped entirely: no file is written for it.
[Details ›](/frontend/static-site-generation#declaring-staticparams)

#### Where do I declare `staticParams`?

Wherever the framework exposes named exports from a page module - the value is the same list of positional parameter sets everywhere:

* **React / SolidJS**: `export const staticParams = defineStaticParams<"...">([...])`, importing `defineStaticParams` from `_/core`
* **Vue**: the same, in a plain `<script>` block (`<script setup>` can't hold named exports)
* **Svelte**: the same, in a `<script module>` block
* **MDX**: a `staticParams` list in the page's frontmatter

[Details ›](/frontend/static-site-generation#declaring-staticparams)

#### How do I fetch data for pre-rendered pages?

The same `loader` (React, Vue, Svelte, MDX) or `preload` (SolidJS) export you'd use otherwise,
combined with `staticParams`: it runs **once per declared entry**,
receiving that entry's own params, and the fetched data is baked into that entry's pre-rendered HTML.

Those calls take the in-process path, inside the build: SSG starts a disposable SSR server and requests each route from it.
So the build needs the access production has - the real database, the CMS, whatever the routes read.
The usual shape is a CI workflow that ships the sources to the production environment (or a runner with the same credentials and network reach) and builds there.

A route that can't be rendered is never emitted as a client shell.
Pre-rendering carries on through the rest, then either writes the whole set or - if anything failed - writes nothing and throws a summary.
[Details ›](/frontend/static-site-generation#error-handling)

#### Where does the SSG output go, and what do I deploy?

`dist/<folder>/ssg/` - a complete static site: one `index.html` per route, the hashed `assets/`,
and your `public/` files copied to the root.
The tree is rooted at the folder's `base`, so a folder with `base: "/admin"` is deployed at `/admin/` on the host.
Nothing in it depends on the `ssr/` or `client/` directories at serve time.
[Details ›](/frontend/static-site-generation#output)

#### Is a 404 page included in the SSG output?

No - nothing is pre-rendered for unmatched paths, so point your host's own not-found setting at whatever it expects
(`404.html` on GitHub Pages and Netlify, `error_page` in Nginx).
[Details ›](/frontend/error-pages)

#### How do I turn SSG off?

Set `frontend.ssg: false` in that folder's `kosmo.config.ts`.
The folder keeps rendering normally, it just stops emitting static routes.
[Details ›](/frontend/static-site-generation)

### Build & Deployment

#### How do I build all folders vs one?

`pnpm build` (all) or `pnpm build front` (one).
[Details ›](/dev-build-run/building-for-production)

#### How do I run the production build locally?

`pnpm preview` (all) or `pnpm preview front` (one). It builds, serves the result through `dist/run.js`,
and rebuilds on every change.
Server-rendered pages, bundled assets and the production validation policy - the real thing, not the dev server.
[Details ›](/dev-build-run/production-preview)

#### Does preview have HMR?

No. A change triggers a full rebuild and a full page reload.
HMR patches modules in a running graph, which a production bundle doesn't have -
and a preview you can't trust is worse than none.
Use `pnpm dev` to iterate, `pnpm preview` to verify.
[Details ›](/dev-build-run/production-preview#hot-reload-not-hmr)

#### Can I run preview and the dev server at the same time?

Yes - preview listens on `previewPort` (`4558` by default), separate from `devPort`.
[Details ›](/dev-build-run/production-preview)

#### What's the build output layout?

`dist/run.js` (dispatcher over every folder) plus one directory per folder:
`api/` (`app.js` factory + `server.js` bundled server), `client/` (`assets/` + `index.html`),
and `ssr/` (`app.js` + `server.js` + `assets/` folder, only when SSR is enabled).
[Details ›](/dev-build-run/building-for-production#build-output)

#### What's the simplest way to run my app in production?

`node dist/run.js -p 4556` - one process serving every source folder, dispatched by each folder's `frontend.base` and `backend.base`.
It's built on `node:http`, so `bun` and `deno run -A` work too.
[Details ›](/dev-build-run/building-for-production#one-entry-point-for-the-whole-project)

#### Can I run a single folder's API instead?

Yes - `node dist/front/api/server.js`. For more control, use the app factory at `dist/<folder>/api/app.js`.
Useful when folders have separate lifecycles.
[Details ›](/dev-build-run/building-for-production#running-the-api-server)

#### How do I mount the app factory per runtime?

* *Hono*: `app.fetch` is a Web Fetch handler - on Node use `getRequestListener` from `@hono/node-server`.
  Deno via `Deno.serve`, Bun via `Bun.serve`.
* *H3*: `app.fetch` is a Web Fetch handler - on Node use `toNodeHandler` from `h3/node` (then createServer).
  Deno via `Deno.serve`, Bun via `Bun.serve`.
* *Koa*: On Node use `app.listen()`. On Deno/Bun use `app.callback()` via a compat layer, not their native serve APIs.
  [Details ›](/dev-build-run/building-for-production#running-the-api-server)

#### Why are the API and SSR servers separate?

They're built as separate bundles so you can deploy, scale, and run them independently. But the
SSR bundle already includes the API and serves it on the same port, so an SSR deployment doesn't
need a separate API process. Running the API server on its own is only needed for CSR folders,
where there's no SSR bundle to carry it.
[Details ›](/dev-build-run/building-for-production#build-output)

### OpenAPI

#### Does it derive OpenAPI automatically?

Yes - OpenAPI 3.1 directly from route definitions, TypeScript types, `VRefine` constraints,
parameters, and responses. No manual schema authoring or annotation layers.
[Details ›](/openapi)

#### How do I enable and configure it?

Add an `openapi` block under `backend` in `kosmo.config.ts`. Required: `outfile`, `openapi` (e.g. `"3.1.0"`),
`info` (`title` + `version`), `servers` (each `url` + optional `description`).
Optional `info`: `summary`, `description` (markdown), `termsOfService`, `contact`, `license`.
[Details ›](/openapi#configuration)

#### Why does one route with an optional param produce two paths?

OpenAPI requires all path params to be mandatory, so a route like `users/[id]/posts/{postId}`
emits both `/users/{id}/posts/{postId}` and `/users/{id}/posts` -
both referencing the same handlers and schemas.
[Details ›](/openapi#derived-specification)

#### Does the spec update automatically?

Yes - it is recomputed in the background whenever you change routes, types, or schemas, alongside validation and fetch clients.
[Details ›](/openapi#derived-specification)

#### How do I serve the spec?

Point Swagger UI, Redoc, or Stoplight Elements at the derived file.
[Details ›](/openapi#derived-specification)

### Dev Workflow & Internals

#### What happens when the dev server starts?

Vite compiles `api/app.ts`; the dev server serves both client pages and your API routes;
requests are routed between Vite and your API; a file watcher monitors API files for changes.
[Details ›](/dev-build-run/development-workflow#what-happens-on-start)

#### What are the api/dev.ts hooks?

`requestHandler` (returns the API request handler) and `teardownHandler`
(runs before each API reload).
[Details ›](/dev-build-run/development-workflow#api-dev-ts)

#### How do I add custom request routing (e.g. WebSockets)?

Override `requestHandler` in `api/dev.ts` for custom dispatch, WebSocket handling,
multi-handler setups, etc.
[Details ›](/dev-build-run/development-workflow#api-dev-ts)

#### Why are my DB connections leaking during development?

Frequent rebuilds can exhaust connections. Close connections and release resources
in `teardownHandler`, which runs before each reload.
[Details ›](/dev-build-run/development-workflow#api-dev-ts)

#### How do I inspect registered routes and their middleware?

Pass the `debug` option to `appFactory` in `api/app.ts`:
`debug: true` prints each route's path, methods, middleware chain (by slot), and handler.
For targeted output pass one of `"headline"` / `"methods"` / `"middleware"` / `"handler"`,
or pass a function `debug(log, route)` for a custom logger - `log` carries all four parts plus `full`.
[Details ›](/dev-build-run/development-workflow#inspecting-api-routes)

#### Why should I name my middleware functions?

Named functions print by name in the debug output; anonymous ones print only their first line,
which is much harder to read.
[Details ›](/dev-build-run/development-workflow#inspecting-api-routes)

#### How does schema derivation performance scale?

With type complexity - simple routes are near-instant, deep hierarchies with many dependencies
take a few seconds. Derivation runs in parallel with the Vite dev server and is cached per file,
so schemas are recomputed only when the route file or a type dependency changes.
By the time you switch to the browser, the schema is ready.
[Details ›](/validation/performance)

#### When does a slow full rebuild happen?

Deleting the `lib` folder manually, or a KosmoJS update bumping the cache version.
On large projects this can take minutes - the same category as clearing `node_modules`
or regenerating a Prisma client, not part of the normal edit-test cycle.
[Details ›](/validation/performance#when-it-becomes-noticeable)

#### How does this compare to Zod/Yup on performance vs maintenance?

Zod/Yup have zero derivation overhead because you hand-write the schemas -
eliminating derivation time but adding ongoing maintenance and drift risk.
KosmoJS trades a few seconds of machine time for eliminating that manual work entirely.
[Details ›](/validation/performance#machine-time-vs-human-time)

#### Where does derived code live?

In `lib`, kept out of your source directories and bundled like any other dependency
at production build time. Treat it as a build artifact - you don't need to read it.
[Details ›](/validation/intro#how-derivation-works)

### Mental Model & Positioning

#### What is KosmoJS the equivalent of?

A meta-framework that owns routing conventions, the validation pipeline, middleware composition,
dev workflow, and build orchestration - while you keep control of backend, frontend,
state, styling, database, and deploy target.
[Details ›](/about)

#### Is it full-stack like Next, or just router + build orchestrator?

Both sides, but with an explicit client/server boundary rather than a unified Server Components model.
You get directory routing for `api/` and `pages/`, plus typed validation, derived fetch clients,
OpenAPI, opt-in SSR, and build orchestration.
[Details ›](/features)

#### Does it pick a frontend for me like Next?

No - you choose React, Vue, SolidJS, Svelte, or MDX per source folder, and can mix them across folders.
[Details ›](/frontend/intro)

#### Does the Svelte support require SvelteKit?

No - KosmoJS uses only Svelte's UI layer (component compilation, `mount`/`hydrate`),
not SvelteKit. Routing, data loading, and SSR come from KosmoJS itself, so a Svelte
page uses the same `loader` export + `useLoaderData()` hook as MDX, not SvelteKit's
`load` function or `+page` files.
[Details ›](/frontend/intro)

#### How does it compare to TanStack's "bring your own everything"?

Similar spirit on the app layer - unopinionated about state/styling/data libraries -
but it adds conventions for routing, validation, and build that TanStack leaves to you,
and it enforces type safety at runtime (derived validators), not only at compile time.
[Details ›](/about)

#### Is it opinionated about state/styling/data fetching?

No - you keep full control. KosmoJS handles infrastructure, not your app stack.
[Details ›](/about)

#### Does it own deployment like Next/Vercel?

No platform lock-in. It's a standard Node/Vite app -
deploy the bundled servers to Node/Bun/Deno/edge yourself.
You can still deploy to Vercel as a Node app, but there are no Vercel-specific features
(and no dependence on them).
[Details ›](/dev-build-run/building-for-production#running-the-api-server)

#### What does it give me over Vite + React Router + Hono wired by hand?

Directory routing for both sides, derived runtime validators from TS types,
derived typed fetch clients, automatic OpenAPI, multi-folder orchestration,
and per-folder build/deploy - without the DIY glue that becomes load-bearing.
[Details ›](/features)

#### Is it a meta-framework or monorepo tooling?

A meta-framework using source folders - monorepo structure and independence without workspaces,
package boundaries, internal dependency graphs, or build-cache configs.
[Details ›](/about)

### Routing

#### What's the equivalent of Next's `app/page.tsx`?

A folder with an `index` file: `pages/users/[id]/index.tsx` -> `/users/:id`.
(TanStack file-based plugin users: same idea, folder-driven.)
[Details ›](/routing/intro#how-it-works)

#### Why folders-with-`index` instead of `page.tsx`?

Only `index` is the route; siblings are colocated helpers - unambiguous at scale.
[Details ›](/routing/rationale)

#### How do params map to Next's / TanStack's?

* `[id]` <-> Next `[id]` / TanStack `$id` (required)
* `{id}` <-> optional
* `{...path}` <-> Next `[...slug]` (splat/catch-all)

Different sigils, same concepts.
[Details ›](/routing/params)

#### Catch-all / optional catch-all (`[[...slug]]`)?

Splat `{...path}` covers both. It matches any number of segments including zero,
so it behaves like Next's optional catch-all `[[...slug]]` - `docs/{...path}` matches `/docs`
as well as `/docs/a/b/c`. There's no separate required-vs-optional catch-all distinction to manage.
[Details ›](/routing/params#splat-parameters)

#### Type-safe params like TanStack Router?

Yes - refine params via the inline tuple type arg to `defineRoute`;
`ctx.validated.params` carries the refined type, validated at runtime
(stronger than TanStack's compile-time-only route typing,
which doesn't validate request bodies by itself).
[Details ›](/backend/type-safety#typing-params)

#### Where's the central route tree (TanStack `routeTree.gen.ts`) / route config object?

There isn't one you register. Routing is filesystem-driven;
route configs are derived per source folder into `lib/` for the native router to consume.
Treat derived code as a build artifact.
[Details ›](/frontend/routing#routes)

#### Route groups like Next's `(group)`?

There's no route-group syntax, and it isn't needed. Next's `(group)` is a lightweight way
to organize routes without affecting the URL - a workaround for separating concerns inside one app.
KosmoJS separates concerns at a higher level: source folders are independent apps
with their own framework, base URL, middleware, and build,
so the separation route groups gesture at is structural here, not a naming convention.
[Details ›](/routing/intro)

#### Parallel / intercepting routes (`@slot`, `(.)`)?

These are Next App Router features with no KosmoJS equivalent.

Parallel routes (`@slot`) render several independent pages into named slots of the same layout at once -
e.g. a dashboard showing a feed and an analytics panel side by side,
each with its own loading and error state.

Intercepting routes (`(.)`, `(..)`) show a route in a different context depending on how you arrive:
the classic case is clicking a photo to open it in a modal over the current page,
while loading the same URL directly renders the full photo page.

KosmoJS has neither convention - it maps one folder to one route.
You'd build the same UX with your framework's own tools:
render multiple components in a layout and fetch their data independently for the parallel case,
and use client-side modal state (or your router's modal patterns) for the intercepting case.
[Details ›](/routing/intro)

#### Nested layouts vs Next `layout.tsx` / TanStack `_layout`?

Same idea - a `layout` file wraps its folder and subfolders, nesting by folders,
rendered outward-in via `<Outlet/>` (React), `<RouterView/>` (Vue), `props.children` (Solid/MDX), or `{@render children()}` (Svelte).
[Details ›](/frontend/layouts#define-a-layout)

#### Do layouts persist state across navigation like App Router?

Yes, in the normal case. When you navigate between sibling routes under the same layout,
only the child swaps in - the layout component stays mounted,
so it doesn't re-render and its state is preserved.
This is the standard behavior of the underlying routers (React Router, Vue Router, Solid Router)
that KosmoJS registers routes with. A layout only remounts when navigation moves outside its subtree.
[Details ›](/frontend/layouts)

#### `loading.tsx` / `error.tsx` / `not-found.tsx`?

There are no per-route special files for these, because they're handled with each framework's
own primitives rather than a KosmoJS file convention.

Global loading, suspense, and error boundaries live at the `app.*` level,
using the native principles of your chosen framework.

Not-found has a built-in: a `pages/404.*` component is rendered for unmatched routes.
Backend errors are separate - they centralize in `api/errors.ts`.
[Details ›](/frontend/layouts#global-layout-via-app-file)

#### `beforeLoad` / search-param validation hook?

KosmoJS doesn't add a proprietary `beforeLoad`-style hook - it leaves your framework's
primitives untouched, so you use the native pattern directly:

* React Router's `loader`
* Solid Router's `preload`
* Vue's `loader` export for data; Vue Router's navigation guards remain available
  for pre-load checks and redirects

For the data contract itself, search params are validated via the `query` target
on handlers (with VRefine constraints) and surfaced through the derived,
client-side-validating fetch clients.
[Details ›](/frontend/data-preload#page-integration)

#### Typed/validated search params like TanStack search schemas?

Not implemented yet - it's a considered feature.
KosmoJS validates query params on the API contract
(the `query` target gives full types and constraints, surfaced through the fetch clients),
but there's no router-level `validateSearch` that types `useSearch()` on the *page route*
the way TanStack does - query typing centers on the API/fetch boundary,
not page-route search state. For now, read and parse search params with your framework's native router.
[Details ›](/validation/payload#validation-targets)

### Data Fetching

#### React Server Components / `"use server"` boundary?

No RSC, and no `"use client"`/`"use server"` directive boundary - by design, not omission.
KosmoJS keeps the battle-tested industry standard: server code in `api/`,
client code in `pages/`, and a plain HTTP API between them with typed fetch clients across the wire.
There's no interleaving of server and client code in one file and no new mental model to learn -
the boundary is the network call. Boring, as in 2015 - and boring is a feature here. And with
the isomorphic fetch client that boundary costs nothing on the server: during SSR the call runs
in-process, so there's no network layer at all.
[Details ›](/frontend/intro)

#### How about server functions?

There aren't any, and you don't need them. A server function exists to run server-only code from
the client without hand-writing an endpoint; KosmoJS gives you that through the API route plus its
derived typed client. The same client is isomorphic - during SSR it calls the route in-process
(no network hop), on the client it's a same-origin request - so one typed call covers both sides
without a separate server-function primitive.
[Details ›](/fetch/isomorphic-clients)

#### Can a page fetch from the database server-side without an API hop?

Not the RSC way - data flows through the API layer, not direct DB access in the page.
But during SSR that isn't a network hop: the isomorphic fetch client dispatches to the
API route in-process (no socket), so you get the API boundary without the round-trip cost.
The de-facto model is API routes + fetch clients + framework loader.
[Details ›](/fetch/isomorphic-clients)

#### Loaders like TanStack Start/Router?

Yes, every framework uses own pattern - `export loader` on React / Vue / Svelte / MDX, `export preload` on SolidJS.
The loader is simply your fetch client's method exported as `loader`/`preload`,
so the typed response flows into `useLoaderData`/`createAsync`.
[Details ›](/frontend/data-preload#page-integration)

#### Is there loader caching / staleness / `loaderDeps`?

No built-in loader cache - React/Solid reuse the in-flight/cached result for that navigation;
SolidJS `preload` results are cached/reused by `createAsync`.
For real caching, enable TanStack Query (a first-class option).
[Details ›](/frontend/tanstack-query)

#### How do I enable TanStack Query?

Turn it on when you create the source folder - interactive mode asks,
or pass `--tsq` non-interactively (`pnpm folder front --frontend react --tsq`).

To add it later, set `tanstack` in the `frontend` block of `kosmo.config.ts`
(`frontend: { tanstack: { query: true } }`).

Once it's on, everything is wired - no setup, no provider to place - you just start using it in your components.
[Details ›](/frontend/tanstack-query#enabling-and-using-it)

#### How do I read data with TanStack Query once it's enabled?

Just write the read: `useQuery` against a fetch client (`queryKey` + `queryFn: () => GET([id])`) in a component.
Frameworks differ only at the hook: React and Vue take the options object directly;
Solid and Svelte take a thunk (`() => (...)`) to stay reactive;
and Svelte's hook is `createQuery`, not `useQuery`.
[Details ›](/frontend/tanstack-query#basic-usage)

#### How do I warm TanStack Query on the server (SSR)?

To render a page's data on the server and hydrate it warm, you wire it yourself with TanStack's own primitives -
`dehydrate` on the server, `HydrationBoundary`/`hydrate` on the client - following your framework's official SSR guide.

The one KosmoJS-specific detail: get the request-scoped client from `getQueryClient()` in your loader,
so you prefetch into the same client the render reads, and share one query-options
helper between loader and component so the `queryKey` matches.

(Solid needs no boundary - its `generateHydrationScript()` carries the cache automatically.)
[Details ›](/frontend/tanstack-query#ssr-warmup-advanced)

#### How do I do mutations with TanStack Query?

Exactly as TanStack documents - no KosmoJS-specific wiring.
`mutationFn` calls the fetch client's `POST`/`PUT`/etc.,
and `queryClient.invalidateQueries({ queryKey })` in `onSuccess` refetches the affected queries in place -
the thing a loader alone can't do without re-navigating.
Mutations are client-side, so SSR doesn't affect them.
[Details ›](/frontend/tanstack-query#mutations-and-invalidation)

#### How do I get a Query client, or configure one?

`_/query` provides two exports: `getQueryClient()` and `createQueryClient(options)`.

Use `createQueryClient(options)` when you need a custom staleTime, retry policy, etc.
Create the custom client in your `app.{tsx,vue,svelte}` and provide it as a prop to `AppProvider`.
[Details ›](/frontend/tanstack-query#configuring-a-custom-client)

#### Does SSR data fetching work without extra plumbing?

Yes - the fetch client is isomorphic.

During SSR a render-time fetch (a `loader` or `createAsync`) dispatches to the API route in-process,
and the framework's own hydration carries the result to the client:
every framework reuses the server-rendered data without re-fetching.

React and Solid do it through their built-in hydration;
Vue, Svelte, and MDX serialize the loader result into the page
and read it on the client before the loader would fetch.
You don't wire dehydrate/hydrate for that.

TanStack Query is an optional opt-in layer - if you enable it and want its cache serialized across SSR,
that plumbing is on you (via TanStack's own dehydrate/hydrate),
but it isn't required for fetch-client data to survive hydration.
[Details ›](/fetch/isomorphic-clients)

#### fetch caching / `revalidatePath` / `revalidateTag` / ISR?

No fetch cache extensions, no tag/path revalidation, no ISR. Cache at the CDN/proxy layer;
SSG is full static generation. After a mutation, refetch or invalidate your own client cache.
[Details ›](/openapi)

#### Preload on link hover/intent - which frameworks?

React `loader` runs on load/hover/navigation; SolidJS `preload` runs on hover/intent
(cached by `query`/`createAsync`); Vue, Svelte, and MDX run their `loader` before render.
Loader (React/Vue/Svelte/MDX) and preload (SolidJS) make data ready before render, eliminating route-level spinners.
[Details ›](/frontend/data-preload#how-it-works)

### Server Actions / Mutations / RPC

#### Server Actions (`"use server"`) / Start server functions (`createServerFn`)?

No server actions and no RPC-style server functions.
Do mutations by defining a normal API route (`POST`/`PUT`/`DELETE`)
and calling its derived typed client, validated client-side first.
(There's no progressive-enhancement no-JS form submit as a first-class feature,
and no `useFormState`/`useActionState` equivalent -
use your framework's form state plus the client's `validationSchemas` for field errors.)
[Details ›](/fetch/start#method-signatures)

#### End-to-end RPC type safety like tRPC?

Effectively yes via fetch clients - params, payload, and response types derive from the same route definition,
with client-side validation before the request.
The difference: it's route-based (path keys + HTTP methods) rather than procedure-based,
and backed by derived TypeBox validators plus automatic OpenAPI.
[Details ›](/fetch/intro)

#### Client-side input validation like a tRPC input schema?

Yes - the client validates params/payload before sending, using the same server schemas,
so client-valid and server-accepted stay in sync.
[Details ›](/fetch/validation#validation-schemas)

### Backend / API

#### Next Route Handlers (`route.ts`) / Start `createAPIFileRoute` equivalent?

`defineRoute` returning an array of method handlers in `api/.../index.ts` - same idea,
plus validation and a fetch client for free. You don't write `Response.json()`.
There's no `NextRequest`/`NextResponse` - it's the native Hono/H3/Koa context.
[Details ›](/backend/intro#defining-endpoints)

#### Why an array instead of named method exports?

The factory yields method builders + `use`; returning an array lets you compose middleware
and methods together with shared types.
[Details ›](/backend/intro#defining-endpoints)

#### Run on the edge / Cloudflare / Deno / Bun?

With Hono and H3 the API runs on Node/Deno/Bun/Cloudflare Workers and edge platforms unchanged (`app.fetch`).
Koa runs via the `node:http` compat layer. There's no automatic serverless/edge function packaging like Next -
you run the bundled server or wire `app.fetch` into an edge runtime yourself.
[Details ›](/dev-build-run/building-for-production#running-the-api-server)

#### Edge middleware (`middleware.ts`) vs cascading `use.ts`?

There's no global edge-middleware file or client-route interception layer.
API middleware is per-subtree via auto-wrapping `use.ts` plus slots;
to gate a subtree behind auth, drop a `use.ts` in its folder (typed context via `UseT`).
For the client side, use the global `App.*` wrapper or a layout.
[Details ›](/backend/cascading-middleware#how-it-works)

#### Bring Hono ecosystem middleware?

Yes - e.g. `hono-rate-limiter` is shown wired through `use`.
There's no bundled auth (no NextAuth integration) - wire your own in middleware:
verify token, set `ctx.state.user` / `ctx.set("user")`.
[Details ›](/backend/cascading-middleware#common-use-cases)

#### Typed env/bindings (e.g. D1)?

Hono bindings are typed via `defineRoute`'s 4th type arg or `DefaultBindings` in `api/env.d.ts`
(e.g. `DB: D1Database`), read via `ctx.env.DB`.
[Details ›](/backend/type-safety#typing-state-context)

### Validation & Types

#### Does it use Zod like TanStack often does?

No - "runtype" validation: TS types -> JSON Schema -> TypeBox validators, derived automatically.
You write TS types once; validators are derived, eliminating hand-written schemas
and type/schema drift. One source of truth drives compile-time types, runtime validation,
client validation, and OpenAPI.
[Details ›](/validation/intro#understanding-runtype-validation)

#### Do I lose flexibility without Zod?

Constraints come via `VRefine` (JSON Schema keywords like `minLength`, `pattern`,
`format`, `minimum`, `multipleOf`, `minItems`);
for trusted endpoints set `runtimeValidation: false` to keep types only.
The fetch clients validate with the exact server schemas,
so client and server stay in sync with nothing to keep aligned by hand.
[Details ›](/validation/skip-validation)

#### Can I alias the types used in a `VRefine` constraint, a params tuple or a response tuple?

The contents, yes. The wrapping brackets, no.

**The rule: `[]` and `{}` must be written literally; anything inside them can be aliased**,
local or imported. So `VRefine<string, { pattern: Pattern }>`,
`defineRoute<"users/[id]", [UserID]>` and `response: [200, "json", User]` are all fine -
but hiding the brackets themselves (`defineRoute<"users/[id]", Params>`, `response: ResponseT`) is not.

Those positions are read structurally from the source - which tuple slot is which parameter,
which slot is the status versus the body - so an alias gives it an identifier where it expected a shape.
Both forms typecheck; the failure is silent.
`VRefine`'s base type (first argument) is unrestricted either way.
[Details ›](/validation/refine#keep-the-wrapping-brackets-literal)

#### Is type safety runtime-enforced or compile-only?

Both - the same TS type drives compile-time checks and derived runtime validators.
This is stronger than TanStack's compile-time route typing,
which doesn't validate request bodies on its own.
[Details ›](/validation/intro#understanding-runtype-validation)

#### Why is there a codegen/generation step at all?

Validators are AOT-compiled from types (TanStack users used to instant route typing
should expect a brief generation pass, cached per file, running alongside Vite).
A slow full rebuild only happens when you delete `lib/` or a cache-version bump occurs -
akin to regenerating `routeTree.gen.ts` from scratch, but heavier.
Treat derived code as a build artifact, like the generated route tree.
[Details ›](/validation/performance#machine-time-vs-human-time)

#### Isn't generated code a red flag?

Usually, yes - but the bad reputation belongs to *scaffolding*: code generated once that
you then edit and own, so it drifts from its input.
KosmoJS's `lib/` output is *derivation* - recomputed from a single source on every change, never edited,
in the same category as what `tsc`, the JSX transform and Vite already generate for you.
The `src/` boilerplate it does seed is written **only into blank files**,
so re-seeding can never overwrite your work.
And nothing generated is proprietary: `lib/` holds ordinary Hono/React/TypeBox code you could walk away with.
[Details ›](/essentials/why-codegen)

#### Is derived code committed to git?

Mostly no. `lib/.gitignore` ignores everything except `cache.json` and `types.ts`,
so derived output is treated as a build artifact. What *is* committed is the per-route
derivation cache (`cache.json`, keyed by content hashes of the route and its type dependencies)
so a fresh clone or CI run skips a full rebuild.
Don't add `lib/` to the root `.gitignore` - that would drop the cache and make every clone slow.
[Details ›](/essentials/project-structure#inside-lib)

### Rendering & SSR

#### What decides whether a folder renders on the server or the client?

You do, per folder - set `frontend.ssr` (or pass `--ssr` at creation),
and that folder's production build renders on the server.
A project can mix freely: an SSR marketing folder next to a CSR app folder.

Dev is the exception, and not a choice: `pnpm dev` is always Vite with HMR and client-side rendering,
whatever the folder is configured for. The SSR path is exercised by kosmo preview and in production.
To see server-rendered output during dev, run `pnpm preview`.
[Details ›](/frontend/server-side-render#adding-ssr-support)

#### ISR / on-demand revalidation / PPR?

No ISR/revalidation and no partial prerendering.
[Details ›](/frontend/server-side-render)

#### SSG / static export vs `output: export`?

Closest equivalent, and it works on every frontend: each route renders to static HTML at build time
(`staticParams` supplying the entries for dynamic routes), output to `dist/<folder>/ssg/`.
An MDX folder additionally gets frontmatter-driven head, comparable to Next + MDX/Contentlayer, but built in.
[Details ›](#ssg) · [Migration Tips ›](/essentials/migration-tips)

#### Can I use SSG with React, Vue, SolidJS or Svelte?

Yes - SSG works with any frontend. The folder needs SSR enabled, since pages are rendered at build time by its own SSR server.
[Details ›](#ssg)

#### Islands / partial hydration?

Not offered as a named feature. MDX delivers minimal client JS by default and hydrates;
React/Solid/Vue hydrate the app via `renderFactory`.
[Details ›](/frontend/server-side-render)

#### `metadata` / `generateMetadata` / `<head>` management?

MDX frontmatter drives `<head>` (title/description/head array);
for app frameworks you set head in the SSR entry's returned `head` and in components.
No `metadata` export convention.
[Details ›](/frontend/mdx#frontmatter-head-injection)

### Project Structure, Tooling & Config

#### Different framework per folder, sharing types without `packages/shared`?

Yes - e.g. MDX marketing, React app, Vue admin in one project,
importing types directly across folders with no publishing or workspace protocols.
Folders develop together as one project and deploy independently while sharing infrastructure.
[Details ›](/features)

#### Is Vite exposed/configurable? What replaces `next.config.js`?

It's built on Vite (no proprietary runtime/bundler).
Configure per folder via `kosmo.config.ts` with the `frontend` / `backend` / `validation` blocks,
plus standard Vite config including `plugins`.
There's no `app/` vs `pages/` debate - you're in `src/<folder>/{api,pages}`.
[Details ›](/frontend/intro)

#### Output vs `.next/`, and a `next start` equivalent?

`dist/<folder>/` with `api/`, `client/`, and `ssr/`.
Run `node dist/run.js -p 4556` for the whole project, or a single folder's bundled server:
`node dist/front/api/server.js` (API) or `node dist/front/ssr/server.js -p 4556` (SSR).
No adapter system - Hono/H3 via native runtime servers, Koa via `node:http`.
[Details ›](/dev-build-run/building-for-production#build-output)

#### `next/image` / `next/font` / `next/link` / `next/head` equivalents?

There is a typed `Link` component for type-safe navigation.
Head injection is via MDX frontmatter and the SSR `head`.
No `next/image` (image optimization) nor `next/font` equivalent - bring your own.
[Details ›](/frontend/link-navigation)

#### Vs Next multi-zone?

The source-folder model is the multi-app story: per-folder base URLs, frameworks,
and builds within one project, sharing types and a database layer -
so where Next stitches separate deployments together with multi-zone,
KosmoJS keeps the apps in one codebase with no zone configuration.
[Details ›](/features)

### OpenAPI

#### Does it really derive OpenAPI automatically, and how does it compare to hand-written / tRPC-OpenAPI?

Yes - OpenAPI 3.1 from routes, types, VRefine constraints, params, and responses,
with no manual authoring, kept live as routes change (TanStack has no built-in equivalent).
Serve it with Swagger UI, Redoc, or Stoplight Elements.
[Details ›](/openapi)

***

### Agents

#### Is there guidance for LLM agents writing KosmoJS code?

Yes - [Notes for LLM Agents](/agents) collects what an agent must check before emitting code:
how to tell which frameworks a folder runs, why boilerplate should never be hand-written,
the four validation mistakes that typecheck but fail at runtime, middleware placement,
and why the dev server never shows the SSR path.

Agents should also prefer `https://kosmojs.dev/llms-full.txt` over recall for exact config options,
the full `VRefine` keyword set and scaffold flags.
[Details ›](/agents)

---

---
url: /agents.md
description: >-
  What an LLM agent must check before emitting KosmoJS code - which framework
  the folder runs, who writes the boilerplate, the four validation mistakes that
  typecheck but fail at runtime, middleware placement, and why the dev server
  never shows the SSR path.
---

This page is for **LLM agents** writing KosmoJS code - and for anyone who wants the failure modes in one place.
The conventions here are dense, and most of them fail *silently*: the code typechecks, the server starts, and the wrong thing happens at runtime.

::: tip Prefer the source over memory
Fetch **`https://kosmojs.dev/llms-full.txt`** before relying on recall for details.
:::

## Orient before writing

A source folder is a self-contained app, and almost every convention depends on which frameworks it runs.
Read `src/<folder>/kosmo.config.ts` first - the `frontend` and `backend` blocks are the answer:

| Question | Where to look |
|---|---|
| Which backend? | `backend.stack` - `"hono"` / `"h3"` / `"koa"`. No `backend` block -> frontend-only folder, no `api/` directory. |
| Which frontend? | `frontend.stack` - `"react"` / `"solid"` / `"vue"` / `"svelte"` / `"mdx"`, or the page file extensions. No `frontend` block -> backend-only folder, no `pages/`. |
| SSR? SSG? | `frontend.ssr` / `frontend.ssg`. |
| Where does it serve from? | `frontend.base` and `backend.base` - both full paths, not joined. |

The frontend answer decides more than syntax - data preload, child rendering, layout filenames,
`jsxImportSource` and mixed-segment support all differ per framework.
Consult the [support matrix](/essentials/frameworks) rather than guessing from one example.

**Route or page?** An API route default-exports `defineRoute(...)` returning an array of method handlers.
A page default-exports a component - a **named function**, never an anonymous arrow, which breaks Vite's HMR.

## Never write the boilerplate yourself

When a new route, `use.ts`, page or layout is needed: **create the file empty** and let KosmoJS fill it in.
Imports, factory signatures and seeded-file wiring change between releases,
so recalled boilerplate is the single most likely thing to be wrong.

KosmoJS owns the seeding; you own the logic you put inside it.

Two ways to land it:

* **Local machine** - the running dev server picks the file up on creation and fills it in.
* **Containers, CI, remote sandboxes** - do **not** rely on the dev server.
  File watching inside containers is prone to inotify trouble (limits, wedged instances, lost events),
  which shows up as files that are silently never filled. Create the empty files and run the **build** command instead:
  it resolves routes with exactly the same code, deterministically, with no watcher involved.

## The four silent validation failures

These typecheck cleanly and misbehave at runtime. Check them before debugging anything else.
[Full list ›](/validation/gotchas)

**1. A wrapping bracket hidden behind an alias.** The params tuple, the response tuple and the
`VRefine` constraint object must each have their `[]` / `{}` written **inline**:

```ts
defineRoute<"users/[id]", [number]>      // ✅
type Params = [number];
defineRoute<"users/[id]", Params>        // ❌ brackets hidden
```

Aliases *inside* the brackets are fine - it is the brackets themselves that are read from source.
Hide them and a params tuple rejects **every** request, while a response tuple produces **no schema at all**.

**2. A type named after a built-in.** `Event`, `Response`, `Request`, `Error`, `Date`, `Partial`,
`Record`, `Buffer` and friends are referenced as-is during type flattening,
so the validator sees the built-in instead of your type - no compile error, wrong behaviour at runtime.
Rename with a consistent suffix or prefix (`EventT`, `TResponse`).
[Details ›](/validation/naming-conventions)

**3. Plain `number` where an integer is required.** `number` admits floats.
Use `VRefine<number, { minimum: 1, multipleOf: 1 }>` for an ID -
otherwise `1000.5` passes validation and fails later at the database, turning a clear validation error into a confusing query error.

**4. A non-string type on a target that doesn't coerce.** Only `query` coerces **numbers and booleans**;
route `params` coerce **numbers only**; `headers`, `cookies`, `form` and `raw` never coerce;
`json` carries real types natively.
[Details ›](/validation/payload#validation-targets)

## Legal validation-target combinations

One body target (`json`, `form` or `raw` - mutually exclusive),
plus any mix of metadata targets (`query`, `headers`, `cookies`, valid on every method).
Two body targets, or a body target on a `GET`, is a dev-time error: KosmoJS warns and disables the affected schema.
[Details ›](/validation/payload#validation-targets)

## Declare a `response` when the frontend consumes it

Without a `response`, the fetch client returns `Promise<unknown>` for that method,
there is no `ResponseT` entry, and no response validation or OpenAPI response schema.
Declaring `response: [200, "json", T]` switches on all four at once.
[Details ›](/fetch/type-safety#without-a-response-the-result-is-unknown)

## Middleware placement

Shared across a route subtree -> a [cascading `use.ts`](/backend/cascading-middleware) in that folder:
it auto-wraps the folder and its subfolders and exports a `UseT` that cascades context types downward.
One route only -> an inline `use` inside `defineRoute`.
Global -> the [`api/use.ts`](/backend/middleware).
Before validation -> an [`edge:` prefixed slot](/backend/edge-middleware) on any of the above.
Every request, matched route or not -> [`api/app.ts`](/backend/middleware#app-middleware) - the only
layer that sees preflights, `405`s and unmatched URLs, so CORS belongs here.

Keep cascading middleware generic. It runs for sibling routes too, so a param like `id` may be `undefined` there.

## Navigation and framework hooks

The typed [Link](/frontend/link-navigation) takes a tuple of route name then params in path order -
`to={["users/[id]", 123]}` - plus an optional `query` prop.
TypeScript enforces the param types, so renaming a route folder surfaces an error at every stale `Link`.

`_/use` exists **only in Vue, Svelte and MDX folders**.
In React and SolidJS it does not resolve at all - use `react-router` / `@solidjs/router` instead.
Vue exports `useLoaderData` only;
Svelte and MDX add `useRoute`, `useParams`, `useParamsEntries` and `useSearchParams`,
and MDX adds `useFrontmatter`. `useLoaderData` returns `T | undefined`,
and a **layout** must pass its path-qualified name (`useLoaderData("dashboard/layout")`) where a page passes nothing.
[Details ›](/frontend/hooks)

## The dev server never shows the SSR path

Dev is **always** client-rendered - Vite with HMR - whether or not `frontend.ssr` is on.
The server entry (`renderToString` / `renderToStream`) and any SSG output exist only in a production build.
Do not reason about "the SSR code path" from what the dev server does; run `pnpm preview` to see the real thing.
[Details ›](/dev-build-run/production-preview)

---

---
url: /about.md
description: >-
  KosmoJS - the composable meta-framework. Organize multiple apps with
  directory-based routing, automatic runtime validation, fetch clients, and
  OpenAPI specs.
---

Named after the Greek "Kosmos" (κόσμος) - "order" or "world" - reflecting the focus on organized, structured project architecture.

### 💡 What it does and how

Most projects eventually need more than one app - a marketing site, a customer dashboard,
an admin panel. The usual options work well but at the price of inevitable friction:

**Microservices** - each app in its own repo with its own `package.json`,
its own CI pipeline, its own deploy config. Shared types drift.
A database schema change means coordinating across repos.
You spend more time on infrastructure than on features.

**Monorepos** - everything in one repo, but now you manage
workspaces, package boundaries, internal dependency graphs, build caching configs,
and a `packages/shared` folder that becomes a dumping ground.
The tooling that's supposed to simplify things becomes its own project.

**DIY glue** - skip the tooling, wire it yourself. Shared scripts, custom build steps,
a hand-rolled dev server that stitches apps together. It works at first.
Then the project grows, a second developer joins, and nobody remembers
why `start-all.sh` passes `--legacy-peer-deps` or which app breaks
if you update the shared config. Homegrown infrastructure is cheap to build
and expensive to maintain.

::: info There's a simpler way
**KosmoJS** takes a different, **Vite**-inspired approach: **Source Folders**.
:::

Each app lives in its own folder with its own framework stack, base URL, and build output -
but they're not separate packages. They share one `package.json`, one `node_modules`,
one database layer, one set of types. You choose backend/frontend framework for each source folder,
while routing and validation patterns stay the same across all frameworks:

```
src/
├── app/          - React, Hono backend, base "/app"
├── admin/        - Vue, H3 backend, base "/admin"
└── marketing/    - MDX, no backend, base "/"
```

Need a type from the customer app in the admin dashboard? Import it.
Changed a database model? Every source folder sees the change immediately.
No publishing, no versioning, no workspace protocols.

Each folder has independent routing, middleware, layouts, config, and deploy configuration.
One command starts them all. One command builds them all.
And you can build or deploy a single folder when that's all you need.

### 🛠️ Under the hood

Add a source folder, pick a backend (`Hono`, `H3`, `Koa`) and a frontend (`React`, `Vue`, `SolidJS`, `Svelte`, `MDX`).
Create files in `api/` and `pages/`, and they become routes automatically:

```
src/app/
├── api/
│   └── users/
│       └── [id]/
│           └── index.ts       ->  GET /api/users/:id
└── pages/
    └── users/
        └── [id]/
            └── index.tsx      ->  /users/:id
```

KosmoJS acts as a universal chassis - providing the same consistent way to define routes
for all source folders, regardless of framework, backend or frontend.

Thanks to this architecture, KosmoJS provides:

* [End-to-End Type Safety](/validation/intro)
* [Fetch Clients + OpenAPI](/fetch/intro)
* [Composable Cascading Middleware](/backend/middleware)
* [Nested Layouts](/frontend/layouts)

and [More Features ›](/features)

### ⚖️ How it differs

Most meta-frameworks choose your frontend framework for you and own your deployment model.
Monorepo tools give you flexibility but bury you in configuration.
Microservices give you independence but fragment your codebase.
DIY glue works until it doesn't - and by then it's load-bearing.

KosmoJS takes the best of each: the structure of a monorepo,
the simplicity of a single project, and the independence of separate apps -
without the overhead of any of them.

You keep full control over backend, frontend, state management, styling, database, and deploy target.
KosmoJS handles routing conventions, validation pipeline, middleware composition, development workflow  and build orchestration.

You focus on features, KosmoJS takes care of infrastructure.

Part of how it does that is by generating code - validators, typed clients, route tables, an OpenAPI spec.
If that sets off alarms, it should: most code generation has earned its reputation.
[Why Codegen](/essentials/why-codegen) explains why this kind is the compiler kind rather than the scaffolding kind.

***

---

---
url: /features.md
description: >-
  Explore KosmoJS features including multiple source folders, directory-based
  routing, end-to-end type safety, derived fetch clients, OpenAPI specs, and
  framework freedom - Hono, H3, Koa, React, Solid, Svelte, Vue, MDX.
---

Everything KosmoJS provides, at a glance.

## Multiple Source Folders

Organize distinct concerns - public site, customer app, admin dashboard -
as independent source folders within a single `Vite` project.
Each gets its own set of frameworks, base URL, development workflow and build pipeline.

[Details ›](/tutorial#create-your-first-api-route)

## Directory-Based Routing

Your folder structure defines your routes - for both API and client pages.

```
api/users/[id]/index.ts    -> /api/users/:id
pages/users/[id]/index.tsx -> /users/:id
```

Dynamic parameters: `[id]` required · `{id}` optional · `{...path}` splat.
No separate routing config to maintain - restructure files and routes update automatically.

Mixed segments are also supported for backend routes (and some frontend integrations):

```
products/[category].html/index.ts   -> products/electronics.html
files/[name].[ext]/index.ts         -> files/document.pdf, /files/logo.png
```

[Details ›](/routing/intro)

## End-to-End Type Safety

Write `TypeScript` types once - KosmoJS derives runtime validators automatically.
The same definition drives compile-time checking, runtime validation, type-safe fetch clients, and OpenAPI specs.

```ts
export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: {
      email: VRefine<string, { format: "email" }>;
      age: VRefine<number, { minimum: 18 }>;
    },
    response: [200, "json", User],
  }>(async (ctx) => {
    const { email, age } = ctx.validated.json;
    // payload validated before reaching here
    // response validated before sending
  }),
]);
```

[Details ›](/validation/intro)

## Typed Fetch Clients + OpenAPI

For every API route, KosmoJS produces a fully-typed fetch client
and an OpenAPI 3.1 spec - both derived from the same type definitions.

```ts
import fetchClients from "_/fetch";

const user = await fetchClients["users/[id]"].GET([123]);
// fully typed, validates payload client-side before the request is sent
```

[Fetch Clients ›](/fetch/intro) · [OpenAPI ›](/openapi)

## Isomorphic Fetch

The same fetch client runs on the server and the client.

When a call fires during SSR, the request goes to the API route in-process,
skipping the network while still running the full validation and handler chain.

The result is serialized into the page and reused on hydration,
so the request is not repeated on the client.

```ts
// runs on the server during SSR, on the client during navigation -
// same call, same types, no network hop on the server
export const loader = ({ params }) => fetchClients["users/[id]"].GET([params.id]);
```

[Details ›](/fetch/isomorphic-clients)

## Built-in Streaming SSR

Render pages as a stream instead of a single string - the shell flushes to the
browser early, improving Time-to-First-Byte for large pages or long data-fetching chains.

Each framework streams through its own native renderer,
returning a web-standard `ReadableStream` that works the same on Node, Bun, and Deno;
KosmoJS adds no rendering layer of its own.

Streaming is opt-in - every route defaults to string rendering.
Set `renderMode: "stream"` to stream all routes, or map glob patterns for per-route selection:

```ts [kosmo.config.ts]
frontend: {
  ssr: {
    renderMode: {
      "docs/**": "stream",
    },
  },
}
```

Available for `React`, `SolidJS`, and `Vue`; `Svelte` and `MDX` render to a string.

[Details ›](/frontend/server-side-render#stream-rendering)

## Composable Middleware (Slots)

Global middleware defined in `api/use.ts` can be overridden per-route or per-subtree
using named slots - without removing or bypassing parent middleware entirely.

```ts
// global default in api/use.ts
use(async (ctx, next) => { /* ... */ }, { slot: "logger" })

// override for a specific route
use(async (ctx, next) => { /* custom logger */ }, { slot: "logger" })
```

Slots give you surgical control over middleware composition:
replace only what needs replacing, inherit everything else.
Custom slot names are supported by extending the `UseSlots` interface.

[Details ›](/backend/middleware#slot-composition)

## Cascading Middleware

Place a `use.ts` file in any folder and its middleware automatically wraps
all routes in that folder and its subfolders - no imports or wiring needed.

```
api/admin/use.ts       -> wraps all routes under /api/admin
api/admin/users/use.ts -> wraps only routes under /api/admin/users
```

Parent middleware always runs before child middleware.
Combine with slots to override globals for entire route subtrees.

[Details ›](/backend/cascading-middleware)

## Nested Layouts

Frontend pages support nested layout components that wrap child routes -
compose shared UI (nav, sidebars, auth shells) at any level of the route hierarchy.

```
pages/
  app/
    layout.tsx        ← wraps all /app/* pages
    dashboard/
      layout.tsx      ← wraps all /app/dashboard/* pages
      index.tsx
      settings/
        index.tsx
```

[Details ›](/frontend/routing)

## TanStack Query Integration

Opt into TanStack Query per source folder and KosmoJS wires it for you - the
query client is provided, per-request on the server and a singleton in the
browser, with no setup in your app code. Enabling it is one option; using it is
just importing `useQuery`.

```ts [kosmo.config.ts]
frontend: { stack: "react", base: "/", tanstack: { query: true } }
```

```tsx
// then, in any component - the client is already provided
const { data } = useQuery({ queryKey: ["users", id], queryFn: () => GET([id]) });
```

Works across `React`, `SolidJS`, `Vue`, and `Svelte`, each on its own official
adapter. KosmoJS provides the seamless basic path and stays out of the way of
the rest: advanced SSR warmup uses TanStack's own `dehydrate` and
`HydrationBoundary` directly, not a wrapper that could drift from them.

[Details ›](/frontend/tanstack-query)

## Multiple Frameworks

* **Backend:** `Hono`, `H3`, `Koa` - same routing architecture, middleware, validation and type safety.
* **Frontend:** `React`, `Vue`, `SolidJS`, `Svelte`, `MDX` - same routing/layout/SSR.

Different source folders can use different framework combinations.
When you add a source folder, KosmoJS seeds a ready-to-go setup for your chosen stack -
router config, entry points, TypeScript settings, and all the wiring between them.
Switch frameworks per folder without learning a new set of conventions.

[Details ›](/frontend/intro)

## Built on Proven Tools

No proprietary runtime, no custom bundler, no framework lock-in.
Every layer is a tool you can use, debug, and replace independently.

***

---

---
url: /start.md
description: Get a KosmoJS project running in under five minutes.
---

Zero to a working route in under five minutes.

## Create a Project

### Create a Project - npm

```sh
npm create kosmo demo
```

### Create a Project - pnpm

```sh
pnpm create kosmo demo
```

### Create a Project - yarn

```sh
yarn create kosmo demo
```

### Create a Project (cont.)

A short interactive setup walks you through the choices that matter:
the frontend framework and the backend you want to build with.
Everything else starts with sensible defaults.

Pick whatever feels familiar - nothing here is set in stone,
and any folder you add later can make entirely different choices.

It is also possible to bootstrap in the current folder, just use `.` as name:

```sh
npm create kosmo .
```

***

After bootstrap, `cd` into freshly created project (unless the project was bootstrapped in the current folder):

```sh
cd ./demo
```

#### Install Dependencies

##### Install Dependencies - npm

```sh
npm install
```

##### Install Dependencies - pnpm

```sh
pnpm install
```

##### Install Dependencies - yarn

```sh
yarn install
```

##### Install Dependencies (cont.)

What you have at this point is deliberately minimal:
a `package.json` and your source folder's config with a few empty stub files.
Follow next steps to turn this skeleton into a working app.

## Start the dev server

The dev server completes the setup: it seeds the remaining project files and wires everything together.
From then on it watches your routes and recomputes as you work:

### Start the dev server - npm

```sh
npm run dev
```

### Start the dev server - pnpm

```sh
pnpm dev
```

### Start the dev server - yarn

```sh
yarn dev
```

### Start the dev server (cont.)

Your app is now running at `http://localhost:4556`.

## Create a route

Create the file `api/users/[id]/index.ts` - KosmoJS detects it
and seeds starter code automatically.

Replace the seeded content with something real:

### Create a route - Hono

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

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.req.param();
    return ctx.json({ id, name: "Jane Smith", email: "jane@example.com" });
  }),
]);
```

### Create a route - H3

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

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (event) => {
    const { id } = event.context.params;
    return { id, name: "Jane Smith", email: "jane@example.com" };
  }),
]);
```

### Create a route - Koa

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

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.params;
    ctx.body = { id, name: "Jane Smith", email: "jane@example.com" };
  }),
]);
```

### Create a route (cont.)

Visit `http://localhost:4556/api/users/123`. You should see JSON.

## Create a page

With the dev server still running, create `pages/users/[id]/index.tsx`
(or `.vue` / `.svelte` / `.mdx`).
KosmoJS seeds a placeholder component - replace it with a page that fetches from your API route.
React, SolidJS, and Vue fetch in the component here; Svelte and MDX read through a
`loader` export instead (resolved before render), so they need no loading state:

### Create a page - React

```tsx
// React: pages/users/[id]/index.tsx
import { useState, useEffect } from "react";
import { useParams } from "react-router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export default function UserPage() {
  const { id } = useParams();
  const [user, setUser] = useState(null);

  useEffect(() => { GET([id]).then(setUser); }, [id]);

  return user
    ? <div><h1>{user.name}</h1><p>{user.email}</p></div>
    : <div>Loading...</div>;
}
```

### Create a page - Solid

```tsx
// Solid: pages/users/[id]/index.tsx
import { useParams } from "@solidjs/router";
import { createAsync } from "@solidjs/router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export default function UserPage() {
  const params = useParams();
  const user = createAsync(() => GET([params.id]));

  return user()
    ? <div><h1>{user().name}</h1><p>{user().email}</p></div>
    : <div>Loading...</div>;
}
```

### Create a page - Vue

```vue
<!-- Vue: pages/users/[id]/index.vue -->
<script setup lang="ts">
import { ref, onMounted } from "vue";
import { useRoute } from "vue-router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];
const route = useRoute();
const user = ref(null);

onMounted(async () => { user.value = await GET([route.params.id]); });
</script>

<template>
  <div v-if="user"><h1>{{ user.name }}</h1><p>{{ user.email }}</p></div>
  <div v-else>Loading...</div>
</template>
```

### Create a page - Svelte

```svelte
<!-- Svelte: pages/users/[id]/index.svelte -->
<script module lang="ts">
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export const loader = ({ params }) => GET([params.id]);
</script>

<script lang="ts">
import { useLoaderData } from "_/use";

const user = useLoaderData();
</script>

<div><h1>{user.name}</h1><p>{user.email}</p></div>
```

### Create a page - MDX

```mdx
// MDX: pages/users/[id]/index.mdx
import fetchClients from "_/fetch";
import { useLoaderData } from "_/use";

const { GET } = fetchClients["users/[id]"];

export const loader = ({ params }) => GET([params.id]);

export const UserPage = () => {
  const user = useLoaderData();
  return <div><h1>{user.name}</h1><p>{user.email}</p></div>;
};

<UserPage />
```

### Create a page (cont.)

Visit `http://localhost:4556/users/123`. Your page renders with data from the API.

The fetch client is fully typed - `user.name` and `user.email` autocomplete in your editor,
and invalid parameters are caught before the request leaves the browser.

## What just happened

Your folder structure became your routes:

```
api/users/[id]/index.ts     ->  /api/users/:id
pages/users/[id]/index.tsx  ->  /users/:id
```

`[id]` is a required parameter. `{id}` makes it optional. `{...path}` matches any depth.
The parallel structure between `api/` and `pages/` is intentional -
API endpoints and their corresponding pages are always easy to find.

The fetch client is derived automatically from your API route definition.
Change the API types, and the client updates with them - no manual sync.

***

That's the foundation. From here:

* [Tutorial](/tutorial) - validation, middleware, fetch clients, pages, SSR
* [Project Structure](/essentials/project-structure) - what lives where, and what `@/` `~/` `_/` mean
* [Configuration](/essentials/config) - every `kosmo.config.ts` option
* [CLI](/cli/intro) - every command and flag, interactive and non-interactive
* [Routing](/routing/intro) - parameters, mixed segments, power syntax
* [Framework Support](/essentials/frameworks) - what each framework does and doesn't support
* [Features](/features) - everything KosmoJS provides, at a glance

---

---
url: /tutorial.md
description: >-
  Build a full KosmoJS application step by step - routing, validation,
  middleware, fetch clients, pages, SSR, and multi-folder architecture.
---

A step-by-step walkthrough covering everything KosmoJS provides.

## Create a Project

### Create a Project - npm

```sh
npm create kosmo demo
```

### Create a Project - pnpm

```sh
pnpm create kosmo demo
```

### Create a Project - yarn

```sh
yarn create kosmo demo
```

### Create a Project (cont.)

A short interactive setup creates the project together with your first source folder,
prompting for the framework and backend.

The folder itself defaults to `app` at base `/` (override later, or via flags in CLI mode).

It is also possible to bootstrap in the current folder, just use `.` as name:

```sh
npm create kosmo .
```

Provide the framework/backend up front and no prompts appear:

### Create a Project - npm

```sh
npm create kosmo demo -- --frontend solid --backend hono
```

### Create a Project - pnpm

```sh
pnpm create kosmo demo --frontend solid --backend hono
```

### Create a Project - yarn

```sh
yarn create kosmo demo --frontend solid --backend hono
```

### Create a Project (cont.)

The first source folder is always `app`, serving pages at `/` and its API at `/api`.
Both `frontend` and `backend` can be further configured in `kosmo.config.ts`.

Need no backend? Provide `--no-backend` flag:

### Create a Project - npm

```sh
npm create kosmo demo -- --frontend solid --no-backend
```

### Create a Project - pnpm

```sh
pnpm create kosmo demo --frontend solid --no-backend
```

### Create a Project - yarn

```sh
yarn create kosmo demo --frontend solid --no-backend
```

### Create a Project (cont.)

Same for the frontend, provide the `--no-frontend` flag to get a backend-only setup.

***

After bootstrap, `cd` into freshly created project (unless the project was bootstrapped in the current folder):

```sh
cd ./demo
```

#### Install Dependencies

##### Install Dependencies - npm

```sh
npm install
```

##### Install Dependencies - pnpm

```sh
pnpm install
```

##### Install Dependencies - yarn

```sh
yarn install
```

##### Install Dependencies (cont.)

What you have at this point is deliberately minimal:
a `package.json` and your source folder's config with a few empty stub files.
Follow next steps to turn this skeleton into a working app.

## Start the dev server

The dev server completes the setup: it seeds the remaining project files and wires everything together.
From then on it watches your routes and recomputes as you work:

### Start the dev server - npm

```sh
npm run dev
```

### Start the dev server - pnpm

```sh
pnpm dev
```

### Start the dev server - yarn

```sh
yarn dev
```

### Start the dev server (cont.)

Your app is now running at `http://localhost:4556`.

## Create Your First API Route

Create `api/users/[id]/index.ts` - KosmoJS detects the file and seeds boilerplate:

### Create Your First API Route - Hono

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

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    return ctx.text("users/[id] route starts here - replace this response with real logic.");
  }),
]);
```

### Create Your First API Route - H3

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

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (event) => {
    return "users/[id] route starts here - replace this response with real logic.";
  }),
]);
```

### Create Your First API Route - Koa

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

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    ctx.body = "users/[id] route starts here - replace this response with real logic.";
  }),
]);
```

### Create Your First API Route (cont.)

> Some editors show seeded content immediately; others need a brief unfocus/refocus.

Replace with real logic:

### Create Your First API Route - Hono

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

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.req.param();
    const user = { id, name: "Jane Smith", email: "jane@example.com" };
    return ctx.json(user);
  }),
]);
```

### Create Your First API Route - H3

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

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (event) => {
    const { id } = event.context.params;
    const user = { id, name: "Jane Smith", email: "jane@example.com" };
    return user;
  }),
]);
```

### Create Your First API Route - Koa

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

export default defineRoute<"users/[id]">(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.params;
    const user = { id, name: "Jane Smith", email: "jane@example.com" };
    ctx.body = user;
  }),
]);
```

### Create Your First API Route (cont.)

With dev server running, visit `http://localhost:4556/api/users/123`:

[Details ›](/backend/intro)

## Add Validation

### Parameter Validation

Pass a tuple as the second type argument to refine params.
Each position maps to a route parameter in order.
Validation works identically across all frameworks, read validated params via `*.validated.params`:

```ts
type User = { id: number; name: string; email: string }

export default defineRoute<"users/[id]", [
  number // [!code hl]
]>(({ GET }) => [
  GET(async (ctx) => {
    const { id } = ctx.validated.params; // id is a validated number [!code hl]
    // ...
  }),
]);
```

Use `VRefine` for additional constraints (no import needed):

```ts
defineRoute<"users/[id]", [
  VRefine<number, { minimum: 1, multipleOf: 1 }> // positive integer
]>
```

Raw params still can be accessed via `ctx.req.param()`/`event.context.params`/`ctx.params`,
but they are untyped strings - prefer `ctx.validated.params`.

### Payload/Response Validation

The first type argument to each method handler defines validation targets.

Metadata targets (any method): `query` · `headers` · `cookies`

Body targets (mutually exclusive, POST/PUT/PATCH only): `json` · `form` · `raw`

#### Payload/Response Validation - Hono

```ts
// Hono: api/users/index.ts
import type { CreateUserPayload, User } from "./types";

export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: CreateUserPayload, // [!code hl]
    response: [200, "json", User] // [!code hl]
  }>(async (ctx) => {
    const { name, email, age } = ctx.validated.json;
    return ctx.json({ id: 1, name, email, age });
  }),
]);
```

#### Payload/Response Validation - H3

```ts
// H3: api/users/index.ts
import type { CreateUserPayload, User } from "./types";

export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: CreateUserPayload, // [!code hl]
    response: [200, "json", User] // [!code hl]
  }>(async (ctx) => {
    const { name, email, age } = ctx.validated.json;
    return { id: 1, name, email, age };
  }),
]);
```

#### Payload/Response Validation - Koa

```ts
// Koa: api/users/index.ts
import type { CreateUserPayload, User } from "./types";

export default defineRoute<"users">(({ POST }) => [
  POST<{
    json: CreateUserPayload, // [!code hl]
    response: [200, "json", User] // [!code hl]
  }>(async (ctx) => {
    const { name, email, age } = ctx.validated.json;
    ctx.body = { id: 1, name, email, age };
  }),
]);
```

#### Payload/Response Validation (cont.)

```ts [./types.ts]
export type CreateUserPayload = {
  name: string;
  email: VRefine<string, { format: "email" }>;
  age?: number;
}

export type User = { id: number; name: string; email: string }
```

Payload is validated before your handler runs. Response is validated before it's sent.

[Details ›](/validation/intro)

## Add Middleware

For simple cases, wire middleware inline with `use`:

```ts
import { logRequest } from "~/middleware/logging";

export default defineRoute<"users/[id]">(({ use, GET }) => [
  use(logRequest),
  GET(async (ctx) => { /* ... */ }),
]);
```

For anything shared across routes, use cascading middleware instead.
Create `api/users/use.ts` - it wraps every route under `/api/users` automatically:

```ts [api/users/use.ts]
import { use } from "_/api";

export default [
  use(async (ctx, next) => {
    // runs for every route under /api/users
    return next();
  })
];
```

No imports in route files, no repetition. Parent `use.ts` files wrap child routes automatically.

[Details ›](/backend/middleware)

## Fetch Clients

Fetch clients are fully typed and validated client-side using the same high-performance
TypeBox validators as the server - identical results, no duplication, no drift.

Invalid requests are caught before they leave the browser:

### Fetch Clients - React

```tsx
// React: pages/users/[id]/index.tsx
import { useState, useEffect } from "react";
import { useParams } from "react-router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export default function UserPage() {
  const params = useParams();
  const [user, setUser] = useState(null);
  useEffect(() => { GET([params.id]).then(setUser); }, [params.id]);
  // ...
}
```

### Fetch Clients - Solid

```tsx
// Solid: pages/users/[id]/index.tsx
import { useParams, createAsync } from "@solidjs/router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export default function UserPage() {
  const params = useParams();
  const user = createAsync(() => GET([params.id]));
  // ...
}
```

### Fetch Clients - Vue

```vue
<!-- Vue: pages/users/[id]/index.vue -->
<script setup lang="ts">
import { ref, onMounted } from "vue";
import { useRoute } from "vue-router";
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];
const route = useRoute();
const user = ref(null);
onMounted(async () => { user.value = await GET([route.params.id]); });
</script>
```

### Fetch Clients - Svelte

```svelte
<!-- Svelte: pages/users/[id]/index.svelte -->
<script module lang="ts">
import fetchClients from "_/fetch";

const { GET } = fetchClients["users/[id]"];

export const loader = ({ params }) => GET([params.id]);
</script>

<script lang="ts">
import { useLoaderData } from "_/use";

const user = useLoaderData();
// ...
</script>
```

### Fetch Clients - MDX

```mdx
// MDX: pages/users/[id]/index.mdx
import fetchClients from "_/fetch";
import { useLoaderData } from "_/use";

const { GET } = fetchClients["users/[id]"];

export const loader = ({ params }) => GET([params.id]);

export const User = () => {
  const user = useLoaderData();
  // ...
};

<User />
```

### Fetch Clients (cont.)

Server-side validation still runs even when endpoints are called directly - client validation is additive, not a substitute.

[Details ›](/fetch/intro)

## Create Client Pages

Pages live in `pages/` and follow the same directory-based routing as API routes.
Create `pages/users/index.tsx` - KosmoJS seeds framework-specific boilerplate.

Add a layout for shared UI across route groups - create `pages/users/layout.tsx`:

```txt
pages/
└── users/
    ├── layout.tsx    ← wraps all pages under /users
    └── index.tsx
```

Layouts can be nested - deeper layouts wrap inner layouts, matching your route hierarchy.

[Details ›](/frontend/routing)

## Server-Side Rendering

Enable when creating a source folder (`--ssr`), or add it later in `kosmo.config.ts`:

```ts [kosmo.config.ts]
import { defineConfig } from "@kosmojs/dev";

export default defineConfig({
  frontend: {
    // ...
    ssr: true, // [!code ++]
  },
});
```

> Restart dev server after changing `kosmo.config.ts`.

KosmoJS seeds `entry/server.ts` - your SSR orchestration file.
Critical CSS is extracted and inlined automatically; remaining styles load asynchronously.

See it running - `pnpm preview` builds and serves the production output, and rebuilds whenever you save:

```sh
pnpm preview
```

For deployment, `pnpm build` writes `dist/run.js`, which serves every source folder from one process.
Folders are also bundled separately, so they can be deployed, scaled and run independently when that suits you better.

[Details ›](/frontend/server-side-render) ·
[Dev / Build / Run ›](/dev-build-run/building-for-production)

## Add More Source Folders

Your project starts with the source folder created at bootstrap.
As the app grows, add more - one per distinct concern (main app, admin panel, marketing site, etc.).

Each is independent with its own set of frameworks, config, base URL, etc.

### Add More Source Folders - npm

```sh
npm run folder
```

### Add More Source Folders - pnpm

```sh
pnpm folder
```

### Add More Source Folders - yarn

```sh
yarn folder
```

### Add More Source Folders (cont.)

You'll be prompted for the frontend, backend, and more.
The name gives the folder its prefixes: pages at `/<name>`, API at `/<name>/api`.

Non-interactive mode is also supported; pass any flag and no prompts appear:

* `--frontend solid|react|vue|svelte|mdx` or `--no-frontend` (one required)
* `--backend hono|h3|koa` or `--no-backend` (one required)
* `--ssr` to enable server-side rendering
* `--ssg` to enable static side generation
* `--tsq` to enable TanStack Query

### Add More Source Folders - npm

```sh
npm run folder -- <name> --frontend solid --backend hono
```

### Add More Source Folders - pnpm

```sh
pnpm folder <name> --frontend solid --backend hono
```

### Add More Source Folders - yarn

```sh
yarn folder <name> --frontend solid --backend hono
```

### Add More Source Folders (cont.)

Need no backend? Provide the `--no-backend` flag for a frontend-only folder (a static docs or marketing site).

Need no client? Provide the `--no-frontend` flag for a backend-only folder (an API service with no UI).

The choice is always explicit - a forgotten flag is an error, never a silent default:

### Add More Source Folders - npm

```sh
npm run folder -- api  --backend hono --no-frontend   # API only, no UI
npm run folder -- docs --frontend mdx --no-backend    # UI only, no backend
```

### Add More Source Folders - pnpm

```sh
pnpm folder api  --backend hono --no-frontend   # API only, no UI
pnpm folder docs --frontend mdx  --no-backend   # UI only, no backend
```

### Add More Source Folders - yarn

```sh
yarn folder api  --backend hono --no-frontend   # API only, no UI
yarn folder docs --frontend mdx  --no-backend   # UI only, no backend
```

### Add More Source Folders (cont.)

Creating a source folder adds framework-specific dependencies. Install them:

### Add More Source Folders - npm

```sh
npm install
```

### Add More Source Folders - pnpm

```sh
pnpm install
```

### Add More Source Folders - yarn

```sh
yarn install
```

## Directory-Based Routing

Folder names become URL segments. Each route requires an `index` file:

```txt
api/
  users/
    index.ts          -> /api/users
    [id]/
      index.ts        -> /api/users/:id

pages/
  users/
    index.tsx         -> /users
    [id]/
      index.tsx       -> /users/:id
```

Parameters: `[id]` required · `{id}` optional · `{...path}` splat.
Same pattern for API and pages - learn once, use everywhere.

[Details ›](/routing/intro)

## Path Mappings

Your project starts with a minimal `tsconfig.json`:

```json [tsconfig.json]
{
  "extends": "./lib/tsconfig.json",
  "include": ["./lib/*.d.ts"]
}
```

The extended config provides path mappings used throughout the framework.
You can add your own paths, but these prefixes are reserved:

* `@/*` - Root-level imports
* `~/*` - Source folder imports
* `_/*` - Derived code imports

[Project Structure ›](/essentials/project-structure#path-mappings) walks the whole layout - what
lives in `src/` versus `lib/`, and what each alias resolves to.

***

### Next Steps

**Core patterns:** [Routing](/routing/intro) · [Validation](/validation/intro) · [Middleware](/backend/middleware) · [Layouts](/frontend/routing) · [Fetch Clients](/fetch/start)

**Advanced:** [VRefine](/validation/refine) · [OpenAPI](/openapi) · [Production Builds](/dev-build-run/building-for-production)