# Server actions API

Source: https://kitr.dev/packages/actions/api

Every export of `kitr/actions`, `kitr/actions/types`, read from the published type definitions. The [guide](/packages/actions) shows them in use.

## kitr/actions

Re-exports `@tanstack/start-client-core` unchanged, plus the following.

### defineMutation

```ts
function defineMutation<S extends StandardSchemaV1 | undefined = undefined, TOutput = unknown, TContext = {}>(name: string, options: DefineMutationOptions<S, TOutput, TContext>): ServerMutation<InputOf<S>, TOutput, TContext>;
```

Define a mutation whose handler runs on the server, with the cache effects it has on success.

```ts
export const updateProject = defineMutation('projects.update', {
  input: z.object({ id: z.string(), name: z.string().min(2) }),
  effects: (project) => ({ set: [{ key: projectKeys.detail(project.id), data: project }], invalidate: [projectKeys.lists()] }),
  handler: ({ input }) => db.projects.update(input),
})
```

### defineQuery

```ts
function defineQuery<S extends StandardSchemaV1 | undefined = undefined, TOutput = unknown, TContext = {}>(name: string, options: DefineQueryOptions<S, TOutput, TContext>): ServerQuery<InputOf<S>, TOutput, TContext>;
```

Define a query whose handler runs on the server. The name is the registry key `kitr types`
writes to `.kitr/actions.ts`, so `useQuery('projects.list', input)` works with these types.

```ts
export const listProjects = defineQuery('projects.list', {
  input: z.object({ status: z.enum(['open', 'closed']).optional() }),
  handler: ({ input }) => db.projects.findMany({ where: input }),
})
```

### requireSession

```ts
const requireSession: import("@tanstack/react-start").FunctionMiddlewareAfterServer<{}, unknown, undefined, undefined, undefined, undefined, undefined>;
```

Shortcut: a function middleware that rejects anonymous callers. Expects `context.session` from an earlier middleware.

### CallOptions

```ts
interface CallOptions<TContext = unknown> {
  signal?: AbortSignal;
  /** `.run()` only: the middleware context the handler would see. */
  context?: Partial<TContext>;
}
```

Options for a direct call or `.run()`.

### DefineMutationOptions

```ts
interface DefineMutationOptions<S extends StandardSchemaV1 | undefined, TOutput, TContext> extends DefineOperationOptions<S, TOutput, TContext> {
  /** Cache effects applied on the client after success. A function gets the result and the input. */
  effects?: CacheEffect | ((result: TOutput, input: InputOf<S>) => CacheEffect);
}
```

The second argument of `defineMutation`: the shared options plus cache `effects`.

### DefineOperationOptions

```ts
interface DefineOperationOptions<S extends StandardSchemaV1 | undefined, TOutput, TContext> {
  /** Any Standard Schema. Validated on the server; a failure reaches the caller as a VALIDATION error with field errors. */
  input?: S;
  /** TanStack Start function middleware (`createMiddleware({ type: 'function' })`). */
  middleware?: ReadonlyArray<any>;
  /** Runs on the server only. Its code, and anything it imports, never reaches the browser bundle. */
  handler: (ctx: HandlerContext<InputOf<S>, TContext>) => TOutput | Promise<TOutput>;
}
```

Options shared by `defineQuery` and `defineMutation`.

### DefineQueryOptions

```ts
interface DefineQueryOptions<S extends StandardSchemaV1 | undefined, TOutput, TContext> extends DefineOperationOptions<S, TOutput, TContext> {
  /** How long a result counts as fresh, in milliseconds. Carried into the query options. */
  staleTime?: number;
}
```

The second argument of `defineQuery`: the shared options plus `staleTime`.

### HandlerContext

```ts
interface HandlerContext<TInput, TContext> {
  input: TInput;
  /** Context from Start middleware (request, session...). */
  context: TContext;
  signal: AbortSignal;
}
```

What a handler receives: the validated input, Start middleware context, and the request's abort signal.

### ServerMutation

```ts
interface ServerMutation<TInput, TOutput, TContext = unknown> extends MutationDefinition<TInput, TOutput> {
  (input: TInput, options?: {
    signal?: AbortSignal;
  }): Promise<TOutput>;
  readonly name: string;
  /** Validation and the handler in-process, for tests. Skips Start middleware. */
  run(input: TInput, options?: CallOptions<TContext>): Promise<TOutput>;
  readonly serverFn: ServerFn<TOutput>;
}
```

A server mutation: a `MutationDefinition` from `kitr/query` that is also a function. Call it to
mutate, pass it to `useMutation` for pending state and cache effects, or use it by name.

### ServerQuery

```ts
interface ServerQuery<TInput, TOutput, TContext = unknown> extends QueryDefinition<TInput, TOutput> {
  (input: TInput, options?: {
    signal?: AbortSignal;
  }): Promise<TOutput>;
  readonly name: string;
  /** Validation and the handler in-process, for tests. Skips Start middleware. */
  run(input: TInput, options?: CallOptions<TContext>): Promise<TOutput>;
  readonly serverFn: ServerFn<TOutput>;
}
```

A server query: a `QueryDefinition` from `kitr/query` that is also a function. Call it to fetch,
pass `.options(input)` to any TanStack hook or loader, or use it by name once `kitr types` has
registered it.

### ServerFn

```ts
type ServerFn<TOutput> = (opts: {
  data: unknown;
  signal?: AbortSignal;
}) => Promise<Envelope<TOutput>>;
```

The raw TanStack server function behind a definition, for `useServerFn` or middleware composition.

## kitr/actions/types

### renderActions

```ts
function renderActions(found: FoundOperation[], ctx: Pick<GenerateContext, 'importPath'>): string;
```

The generated module for a set of operations. Exported for tests and for `kitr doctor`.

### scanActions

```ts
function scanActions(file: string, source: string): FoundOperation[];
```

Every `export const <id> = defineQuery|defineMutation('<name>'` in one file.

### FoundOperation

```ts
interface FoundOperation {
  /** Project-relative file. */
  file: string;
  /** The exported identifier. */
  exportName: string;
  /** The dotted name passed to `defineQuery` or `defineMutation`. */
  name: string;
  kind: 'query' | 'mutation';
}
```

The `actions` generator for `kitr types`. It reads every file under `app/actions`
(`directories.actions`), finds the exported `defineQuery` and `defineMutation` calls and writes
`.kitr/actions.ts`: the `operations` map `app/app.ts` passes to `createApp`, the same names as a
nested `actions` tree, and the `Operations` augmentation that types `useQuery('projects.list')`.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Server actions

Source: https://kitr.dev/packages/actions

Rename a project, archive an invoice, invite Grace to a team: a button often needs to run a bit of server code and nothing more. An API route, a client for it and types on both sides is a lot of ceremony for that. An action is a function you define once with `defineQuery` or `defineMutation`; the browser calls it as if it were local, and kitr sends the request, validates the input on the server and brings back the result or a typed error.

Actions are [TanStack Start server functions](https://tanstack.com/start/latest/docs/framework/react/server-functions) with four things added: input validation with any Standard Schema, kitr's one error shape so a validation failure lands on the right form field, cache effects after a mutation, and a generated registry that lets a component say `useQuery('projects.list')` with full types.

Actions run on both sides: the handler on the server, the call anywhere. Use them when the only caller is your own React app. When something else calls the same code too, such as a mobile app, a partner or a webhook, use [API routes](/packages/api) instead; they give you URLs, OpenAPI and a typed client.

## Install

```sh
kitr add actions
```

What `kitr add` does:

- Installs `@kitr/actions`, and [server](/packages/server) and [query](/packages/query) first when the project does not have them.
- Adds `@kitr/actions` to `packages` in `kitrrc.ts`.
- Creates an empty `app/actions/` folder (or `directories.actions` from `kitrrc.ts`).
- Adds `#kitr/*` to `paths` and `.kitr/**/*` to `include` in `tsconfig.json`, and `.kitr` to `.gitignore`. Projects from `kitr new` already have both.
- Prefixes the `typecheck` script with `kitr types &&`, so `tsc` always sees current names.
- Edits `app/app.ts`: `import { operations } from '#kitr/actions'` and `createApp({ operations, ... })`.
- Runs `kitr types` once dependencies are installed, which writes `.kitr/actions.ts`.
- Appends an `actions` section to `AGENTS.md`.

`kitr remove actions` reverses every step above except the `tsconfig.json` and `.gitignore` entries, which other generators use too. The `fullstack` and `saas` kits include actions.

## Configure

This package has no config file. Everything is declared on each definition, so a reader of one file sees everything that affects it:

```ts
// app/actions/projects/update.ts
import { defineMutation } from 'kitr/actions'
import { z } from 'zod'

export const updateProject = defineMutation('projects.update', {
  input: z.object({ id: z.string(), name: z.string().min(2) }),
  middleware: [],
  effects: (project) => ({ invalidate: [['projects']] }),
  handler: async ({ input }) => ({ id: input.id, name: input.name }),
})
```

| Option | Default | Description |
| --- | --- | --- |
| `input` | none | Any [Standard Schema](https://standardschema.dev) (zod, valibot, arktype). Validated on the server; a failure reaches the caller as a `VALIDATION` error with `fieldErrors`. Without it the input is `void`. |
| `handler` | required | Runs on the server only. Receives `{ input, context, signal }`. Its code and imports never reach the browser bundle. |
| `middleware` | `[]` | TanStack Start function middleware, run before the handler. Whatever it puts in `context` is typed on the handler. |
| `staleTime` | the query client's | Queries only: how long a result counts as fresh, in milliseconds, carried into the query options. |
| `effects` | none | Mutations only: cache effects applied on the client after success. An object, or a function of `(result, input)`. |

The names you pass, `projects.update` above, go into one generated file:

| File | Written by | Holds |
| --- | --- | --- |
| `.kitr/actions.ts` | `kitr types` | `operations`, a flat map by name; `actions`, the same as a tree; and the `Operations` augmentation that types every name. |
| `.kitr/platforms.d.ts` | `kitr types` | The platform names from `kitrrc.ts`, so `app.platform` is `'site' \| 'api'`. |

`kitr dev` and `kitr build` run `kitr types` first, and the Vite plugin reruns it whenever a file under `app/actions/` changes, so the file is current while you work. It is generated and ignored by git. Set `directories.actions` in `kitrrc.ts` to keep actions somewhere else.

## Your first mutation

Generate a file:

```sh
kitr make:mutation projects/rename
```

Then give it a schema and a handler:

```ts
// app/actions/projects/rename.ts
import { defineMutation } from 'kitr/actions'
import { useDb } from 'kitr/db'
import { useRequestApp } from 'kitr/server'
import { z } from 'zod'
import { app } from '#app/app'
import type { AppDb } from '#config/db'

export const renameProject = defineMutation('projects.rename', {
  input: z.object({ id: z.string(), name: z.string().min(2) }),
  effects: (project) => ({
    set: [{ key: ['projects', 'detail', project.id], data: project }],
    invalidate: [['projects', 'list']],
  }),
  handler: async ({ input }) => {
    const db = useDb<AppDb>(useRequestApp(app))
    return db.projects.update(input.id, { name: input.name })
  },
})
```

Use it in a component by name:

```tsx
// app/components/rename-button.tsx
import { useMutation } from 'kitr/query'

export function RenameButton({ id }: { id: string }) {
  const rename = useMutation('projects.rename')
  return (
    <button disabled={rename.isPending} onClick={() => rename.mutate({ id, name: 'Acme site' })}>
      Rename
    </button>
  )
}
```

Clicking the button sends one request to the server, which validates the input, runs the handler and returns the project. The `set` effect writes it into the detail cache and `invalidate` refetches every project list. `rename.mutate({ id })` is a type error, because `name` is required, and `useMutation('projects.rnaem')` is one too, because the name is not in the registry.

`useRequestApp(app)` returns the app for the current request, or `app` itself when there is none.

## Read data with a query

A query is an action that only reads. It is sent as a GET and cached like any other query:

```ts
// app/actions/projects/list.ts
import { defineQuery } from 'kitr/actions'
import { useDb } from 'kitr/db'
import { useRequestApp } from 'kitr/server'
import { z } from 'zod'
import { app } from '#app/app'
import type { AppDb } from '#config/db'

export const listProjects = defineQuery('projects.list', {
  input: z.object({ status: z.enum(['open', 'archived']).optional() }),
  staleTime: 30_000,
  handler: ({ input }) =>
    useDb<AppDb>(useRequestApp(app)).projects.findMany({ where: { status: input.status } }),
})
```

In a component:

```tsx
// app/components/project-list.tsx
import { useSuspenseQuery } from 'kitr/query'

export function ProjectList() {
  const { data: projects } = useSuspenseQuery('projects.list', { status: 'open' })
  return <ul>{projects.map((p) => <li key={p.id}>{p.name}</li>)}</ul>
}
```

`useQuery`, `useSuspenseQuery` and `queryOptions` from `kitr/query` all take a name as the first argument and the input as the second. When every field of the input is optional, the input can be left out: `useQuery('projects.list')`. The query key is `['action', 'projects.list', input]`, so `['action', 'projects.list']` invalidates every variant.

## Load before the page renders

In a route loader, `queryOptions` by name hands TanStack Router the same options the component uses, so the server fetches once and the browser reuses the result:

```ts
// app/routes/projects/index.tsx
import { createFileRoute } from 'kitr/router'
import { queryOptions } from 'kitr/query'
import { ProjectList } from '#components/project-list'

export const Route = createFileRoute('/projects/')({
  loader: ({ context }) =>
    context.queryClient.ensureQueryData(queryOptions('projects.list', { status: 'open' })),
  component: ProjectList,
})
```

## Call an action outside a component

Every definition is a function. Import it and call it from a loader, a store, an event handler or a job:

```ts
import { renameProject } from '#app/actions/projects/rename'

const project = await renameProject({ id: 'prj_42', name: 'Acme site' })
// => { id: 'prj_42', name: 'Acme site', status: 'open' }
```

In the browser this is one request. On the server, during rendering or inside another handler, Start runs the handler in-process; there is no HTTP hop. A direct call applies no cache effects, because there is no cache in play; use `useMutation` in components for that.

When all you have is the name, `call` from `kitr/query` looks it up in the registry:

```ts
import { call } from 'kitr/query'

await call('projects.rename', { id: 'prj_42', name: 'Acme site' })
const open = await call('projects.list', { status: 'open' })
```

The generated tree gives the same functions grouped by feature, which reads well in scripts:

```ts
import { actions } from '#kitr/actions'

await actions.projects.rename({ id: 'prj_42', name: 'Acme site' })
```

## Use the definition instead of the name

A name resolves through the registry that `createApp({ operations })` fills. When you prefer an import to a string, every hook takes the definition too, with the same types:

```tsx
import { useMutation, useSuspenseQuery } from 'kitr/query'
import { listProjects } from '#app/actions/projects/list'
import { renameProject } from '#app/actions/projects/rename'

const { data } = useSuspenseQuery(listProjects, { status: 'open' })
const rename = useMutation(renameProject)
```

Both forms end in the same TanStack options. Plain TanStack options still work as before: `useQuery({ queryKey, queryFn })` passes straight through.

## Pass your own query and mutation options

The third argument of a query hook, and the second of `useMutation`, are TanStack overrides. The definition's own `queryKey`, `queryFn` and `mutationFn` cannot be replaced; everything else can:

```tsx
const { data } = useQuery('projects.list', { status: 'open' }, { refetchInterval: 10_000 })
const rename = useMutation('projects.rename', {
  onSuccess: (project) => toast(`Renamed to ${project.name}`),
})
```

The mutation's cache effects run first, then your `onSuccess`.

## Protect an action with middleware

Start middleware runs before the handler and can add to `context`. A session middleware reads the request once and puts the session on the context; `requireSession` then rejects anonymous callers with `UNAUTHORIZED`. It expects `context.session` from an earlier middleware:

```ts
// app/actions/middleware/session.ts
import { getRequest } from '@tanstack/react-start/server'
import { createMiddleware } from 'kitr/actions'
import { sessionFromRequest } from '#server/session'

export const sessionMiddleware = createMiddleware({ type: 'function' }).server(async ({ next }) => {
  // Your own lookup: a cookie, a bearer token, an auth adapter. It returns { user } or null.
  const session = await sessionFromRequest(getRequest())
  return next({ context: { session } })
})
```

```ts
// app/actions/projects/archive.ts
import { defineMutation, requireSession } from 'kitr/actions'
import { z } from 'zod'
import { sessionMiddleware } from '#app/actions/middleware/session'

export const archiveProject = defineMutation('projects.archive', {
  middleware: [sessionMiddleware, requireSession],
  input: z.object({ id: z.string() }),
  handler: async ({ input, context }) => {
    // context.session.user is typed here
    return { id: input.id, archivedBy: context.session.user.id }
  },
})
```

`createMiddleware` is re-exported from `kitr/actions` so every middleware uses the same import. Any middleware can wrap the call:

```ts
// app/actions/middleware/timing.ts
import { createMiddleware } from 'kitr/actions'

export const timing = createMiddleware({ type: 'function' }).server(async ({ next }) => {
  const started = Date.now()
  const result = await next()
  console.log(`took ${Date.now() - started}ms`)
  return result
})
```

## Throw an error the caller understands

Throw a `KitrError` and the caller receives the same code, status, message and field errors:

```ts
import { KitrError } from 'kitr/app'

handler: async ({ input }) => {
  const project = await db.projects.find(input.id)
  if (!project) throw KitrError.notFound('Project not found')
  if (project.ownerId !== input.userId) throw KitrError.forbidden()
  if (await db.projects.exists({ name: input.name }))
    throw KitrError.validation({ name: ['A project with this name exists'] })
  return project
}
```

On the client:

```ts
try {
  await renameProject({ id: 'prj_42', name: 'Acme site' })
} catch (error) {
  if (error instanceof KitrError && error.code === 'VALIDATION') error.fieldErrors
  // => { name: ['A project with this name exists'] }
}
```

With [forms](/packages/forms), pass `rename.mutateAsync` to `<Form onSubmit>` and each message appears under its field. Anything that is not a `KitrError` becomes a 500: the real error is logged on the server, and in production the browser sees only `Internal server error`.

## Organise actions by feature

The generator writes one file per action under `app/actions/<feature>/`. The dotted name is yours; the registry only needs it to be unique, and `kitr types` groups the tree by the part before the first dot:

```
app/actions/
├── projects/
│   ├── list.ts      projects.list
│   ├── rename.ts    projects.rename
│   └── archive.ts   projects.archive
└── invoices/
    └── send.ts      invoices.send
```

Any file under `app/actions/` counts, at any depth, except tests and `.d.ts` files. Only `export const <id> = defineQuery('...')` and `export const <id> = defineMutation('...')` with a literal name are picked up; a name built at run time cannot be typed. `kitr types` fails when a name is used twice, is not a dotted identifier, or is both an operation and a group (`projects` and `projects.list`).

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:query <feature>/<name>` | Writes `app/actions/<feature>/<name>.ts` with `defineQuery('<feature>.<name>', ...)`. |
| `kitr make:mutation <feature>/<name>` | Writes `app/actions/<feature>/<name>.ts` with `defineMutation('<feature>.<name>', ...)`. |
| `kitr types` | Runs every type generator and writes `.kitr/`. `--check` fails when a file is stale; `--watch` keeps running; `--only actions` runs one generator. |

```sh
kitr make:query invoices/list
# → write app/actions/invoices/list.ts
kitr types
# → write .kitr/actions.ts
```

`kitr doctor` warns when `.kitr/` is stale.

## Errors

| Code | When | What to do |
| --- | --- | --- |
| `VALIDATION` | The input failed the `input` schema, or the handler threw `KitrError.validation()`. | Read `fieldErrors`; forms show them under the field. |
| `UNAUTHORIZED` | `requireSession` found no `context.session.user`. | Sign the user in, or drop the middleware for public actions. |
| `NOT_FOUND`, `FORBIDDEN` | The handler threw them. | Show the message; the status is 404 or 403. |
| `INTERNAL` | The handler threw anything else. | Check the server log; the browser never sees the details in production. |
| `Nothing is registered` | A name was used before `createApp({ operations })` ran, or `operations` is not passed. | Import `operations` from `#kitr/actions` in `app/app.ts` and pass it to `createApp`. |
| `"x" is a mutation; use useMutation` | A mutation name was given to `useQuery` or `queryOptions`, or the reverse. | Use the hook that matches the kind. |

## Testing

`.run(input, { context })` validates the input and runs the handler in-process, skipping Start middleware and HTTP, so a test needs neither a server nor a browser:

```ts
// test/actions/rename.test.ts
import { KitrError } from 'kitr/app'
import { describe, expect, it } from 'vitest'
import { renameProject } from '#app/actions/projects/rename'

describe('projects.rename', () => {
  it('renames and returns the project', async () => {
    const project = await renameProject.run({ id: 'prj_42', name: 'Acme site' })
    expect(project).toMatchObject({ id: 'prj_42', name: 'Acme site' })
  })

  it('rejects a short name with field errors', async () => {
    await expect(renameProject.run({ id: 'prj_42', name: 'A' })).rejects.toMatchObject({
      code: 'VALIDATION',
      fieldErrors: { name: [expect.any(String)] },
    })
  })

  it('sees the middleware context it is given', async () => {
    const result = await archiveProject.run(
      { id: 'prj_42' },
      { context: { session: { user: { id: 'usr_ada' } } } },
    )
    expect(result.archivedBy).toBe('usr_ada')
  })
})
```

To test a component that uses a name, register the definitions on the test app and render with [testing](/packages/testing):

```tsx
// test/components/rename-button.test.tsx
import { renderWithKitr } from 'kitr/testing/react'
import { createTestApp } from 'kitr/testing'
import { operations } from '#kitr/actions'
import { RenameButton } from '#components/rename-button'

const app = await createTestApp({ operations })
renderWithKitr(<RenameButton id="prj_42" />, { app })
```

The server function itself is a TanStack Start function, so it also works with Start's own test helpers.

## Next steps

- [API reference](/packages/actions/api)
- [TanStack Start server functions](https://tanstack.com/start/latest/docs/framework/react/server-functions), including middleware and `useServerFn`.
- [Query](/packages/query): the hooks, the cache effects and `call`.
- [Forms](/packages/forms): field errors from a mutation.
- [API routes](/packages/api) for the same handlers behind URLs.
- [Type generation](/docs/cli#type-generation): the `kitr types` runner and how a package adds a generator.


# Analytics API

Source: https://kitr.dev/packages/analytics/api

Every export of `kitr/analytics`, `kitr/analytics/provider`, `kitr/analytics/react`, read from the published type definitions. The [guide](/packages/analytics) shows them in use.

## kitr/analytics

### consoleAdapter

```ts
function consoleAdapter(options?: {
  prefix?: string;
}): AnalyticsAdapter;
```

Logs every call. The default in development when no other adapter is configured.

### createAnalytics

```ts
function createAnalytics<E extends EventMap = EventMap>(config?: AnalyticsConfig<E>): Analytics<E>;
```

One API over any number of destinations. Calls made before `enable()` queue (up to 100)
so a consent banner can gate everything, and every adapter call is wrapped so a blocked
script never breaks the app.

### defineEvents

```ts
function defineEvents<E extends EventMap>(): <C extends AnalyticsConfig<E>>(config: C) => C & {
  events?: E;
};
```

Identity helper that fixes the event map type: `const analytics = createAnalytics<AppEvents>(...)`.

### googleAnalytics

```ts
function googleAnalytics(options: {
  measurementId: string;
  debug?: boolean;
}): AnalyticsAdapter;
```

Google Analytics 4 through gtag.js. Loads the script on `init()` (client only) and
forwards page views, events and user ids. `sendPageView: false` is set on config so the
router, not the script, decides what a page view is.

### memoryAdapter

```ts
function memoryAdapter(): AnalyticsAdapter & {
  calls: Array<{
    type: string;
    args: unknown[];
  }>;
};
```

Collects calls in memory. For tests: `expect(adapter.calls).toContainEqual(...)`.

### plausible

```ts
function plausible(options: {
  domain: string;
  apiHost?: string;
}): AnalyticsAdapter;
```

Plausible: one script, `page()` becomes a pageview, `track()` a custom event with props.

### posthog

```ts
function posthog(client: PostHogLike, options: {
  apiKey: string;
  apiHost?: string;
  config?: Record<string, unknown>;
}): AnalyticsAdapter;
```

PostHog through its own client (`posthog-js`), with autocapture of page views turned off so the router drives them.

### defineConfig

```ts
const defineConfig: <const C extends AnalyticsConfig<EventMap>>(config: C) => C;
```

Types the default export of `config/analytics.ts`: adapters, consent queueing, page views and global props.

### Analytics

```ts
interface Analytics<E extends EventMap = EventMap> {
  /** Record a page view. The provider calls it on every route change unless `pageViews` is false. */
  page(path: string, props?: EventProps & {
    url?: string;
    title?: string;
  }): void;
  /** Record an event from the app's event map, with its props. */
  track<K extends keyof E & string>(event: K, ...props: E[K] extends undefined ? [
  ] : [
    E[K]
  ]): void;
  /** Record any event by name. Accepts names outside the event map. */
  track(event: string, props?: EventProps): void;
  /** Attach later events to a user id, after sign-in. `globalProps` are not added. */
  identify(userId: string, traits?: EventProps): void;
  /** Forget the identified user, on sign-out. */
  reset(): void;
  /** Load each adapter's script, then send the queued calls and start sending. Call after consent. */
  enable(): Promise<void>;
  /** Stop sending and empty the queue. Later calls queue again (up to 100) until the next `enable()`. */
  disable(): void;
  /** True once `enable()` has finished and until `disable()`. */
  readonly enabled: boolean;
  /** Add an adapter at runtime (after a consent choice, or lazily). */
  use(adapter: AnalyticsAdapter): void;
  /** Every adapter in use, in the order calls reach them. */
  readonly adapters: readonly AnalyticsAdapter[];
}
```

The analytics service bound as `analytics` in the container and returned by `useAnalytics()`.
Every call goes to each adapter, or waits in a queue until `enable()`.

### AnalyticsAdapter

```ts
interface AnalyticsAdapter {
  /** Shown in devtools and in debug warnings, such as `google-analytics` or `plausible`. */
  name: string;
  /** Load scripts, create clients. Called once on the client when tracking is enabled. */
  init?(): void | Promise<void>;
  /** Record a page view for `path`; `props.url` and `props.title` carry the full URL and document title. */
  page(path: string, props?: EventProps & {
    url?: string;
    title?: string;
  }): void;
  /** Record a named event with its props. */
  track(event: string, props?: EventProps): void;
  /** Attach later events to a user id. Optional; services without user profiles leave it out. */
  identify?(userId: string, traits?: EventProps): void;
  /** Forget the identified user, on sign-out. Optional. */
  reset?(): void;
}
```

What every destination implements. Methods are best-effort and must never throw into app code.

### AnalyticsConfig

```ts
interface AnalyticsConfig<E extends EventMap = EventMap> {
  /** Where calls go. Empty in the provider means the console in development and nothing in production. */
  adapters?: AnalyticsAdapter[];
  /** Start sending immediately (default). Set false to queue until `analytics.enable()` (consent banners). */
  enabled?: boolean;
  /** Track route changes automatically through the router. Default true. */
  pageViews?: boolean;
  /** Props merged into every event (app version, build id). */
  globalProps?: EventProps;
  /** Log every call. Default: `app.environment` is development. */
  debug?: boolean;
  /** Phantom for `defineEvents`. */
  readonly events?: E;
}
```

Options for `config/analytics.ts` and `createAnalytics()`. `E` is the app's event map.

### PostHogLike

```ts
interface PostHogLike {
  /** Start the client with a project API key and options. */
  init(token: string, config?: Record<string, unknown>): unknown;
  /** Send one event, `$pageview` included. */
  capture(event: string, properties?: Record<string, unknown> | null): unknown;
  /** Attach later events to a user id. */
  identify(id?: string, properties?: Record<string, unknown>): void;
  /** Forget the identified user. */
  reset(): void;
}
```

Minimal shape of the posthog-js client; pass `posthog` from `posthog-js` or any compatible object.

### EventMap

```ts
type EventMap = Record<string, EventProps | undefined>;
```

`defineEvents<{ 'project.created': { id: string } }>()` gives `track()` typed names and props.

### EventProps

```ts
type EventProps = Record<string, unknown>;
```

Props sent with an event, a page view or an identify call. Adapters pass them to the vendor as they are.

## kitr/analytics/provider

### analyticsProvider

```ts
const analyticsProvider: import("@kitr/core").KitrProvider;
```

Binds `analytics` into the container from `config/analytics.ts` and, on the client,
tracks route changes. With no adapters configured, development logs to the console
and production sends nothing.

## kitr/analytics/react

### TrackPageViews

```ts
function TrackPageViews(): null;
```

Sends a `page()` on every resolved navigation. Mounted by the provider when
`pageViews` is not false; render it yourself if you build the tree by hand.

### useAnalytics

```ts
function useAnalytics<E extends EventMap = EventMap>(): Analytics<E>;
```

The analytics instance from the container.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Analytics

Source: https://kitr.dev/packages/analytics

Sooner or later someone asks how many people created a project this week, or which page they left from. `kitr/analytics` gives you four calls (`page`, `track`, `identify` and `reset`) and sends each one to the services you configure: [Google Analytics](https://developers.google.com/analytics/devguides/collection/ga4), [Plausible](https://plausible.io/docs), [PostHog](https://posthog.com/docs/libraries/js), or several at once. Page views are counted for you on every route change, every vendor call is wrapped so a blocked script never breaks a button, and calls can wait in a queue until the visitor agrees to tracking.

The examples on this page follow one scenario: Acme's app at `app.acme.com` counts how often Ada creates a project, which plan Grace's team is on, and when Linus pays an invoice.

`kitr/analytics` runs in the browser. On the server it binds the same service so components render, but no vendor script loads. To record events your server owns (a paid invoice, a cancelled subscription), write them to your database or send them from a [job](/packages/jobs); to report errors rather than usage, use [monitoring](/packages/monitoring).

## Install

```sh
kitr add analytics
```

What `kitr add` does:

- Installs `@kitr/analytics`.
- Adds `() => import('@kitr/analytics/provider')` to `providers` and `'@kitr/analytics'` to `packages` in `kitrrc.ts`.
- Adds `VITE_GA_MEASUREMENT_ID: e.string({ optional: true })` to the `public` block of `app/env.ts`, and `VITE_GA_MEASUREMENT_ID=` to `.env.example` (and to `.env` when that file exists).
- Writes `config/analytics.ts` (shown in [Configure](#configure)) and regenerates `config/index.ts`.
- Writes `app/analytics.ts`, the typed list of your events, with `sign-in.completed` and `project.created` to start.
- Adds a `## kitr: analytics` section to `AGENTS.md` telling coding agents to track through `useAnalytics<AppEvents>()`, to declare new events in `app/analytics.ts` first, and never to call gtag or posthog directly.

`kitr add analytics` asks no questions. To edit `package.json` without running the package manager, pass the global flag:

```sh
kitr add analytics --no-install
```

The `saas` and `site` kits include analytics. It is a client package, so in a server-only project `kitr add analytics` prints a warning and skips it.

`kitr remove analytics` removes the provider, the `packages` entry, the dependency and the `AGENTS.md` section, and deletes `config/analytics.ts`. It leaves `app/analytics.ts`, the env variable and every `track()` call in your components, which you delete by hand.

## Configure

`kitr add analytics` writes this file:

```ts
// config/analytics.ts
import { defineConfig, googleAnalytics } from 'kitr/analytics'
import { env } from '#app/env'

/**
 * With no adapters, development logs every event to the console and production sends nothing,
 * so the app works before any vendor is chosen.
 */
export default defineConfig({
  adapters: [
    ...(env.VITE_GA_MEASUREMENT_ID
      ? [googleAnalytics({ measurementId: env.VITE_GA_MEASUREMENT_ID })]
      : []),
    // plausible({ domain: 'example.com' }),
    // posthog(posthogJs, { apiKey: env.VITE_POSTHOG_KEY }),   // pnpm add posthog-js
  ],
  // Consent banners: start queued, then call analytics.enable() once the user agrees.
  // enabled: false,
  globalProps: { app: env.VITE_APP_NAME },
})
```

With `VITE_GA_MEASUREMENT_ID` empty the `adapters` list is empty, and the provider picks a default: in development it logs every call to the console, in production it sends nothing. Your buttons work before you have chosen a vendor.

| Option | Default | Description |
| --- | --- | --- |
| `adapters` | `[]` | Where calls go. Each entry is an adapter such as `googleAnalytics()` or `plausible()`. When empty, the provider uses `consoleAdapter()` in development and nothing in production. |
| `enabled` | `true` | Start sending at once. `false` queues every call (up to 100) until `analytics.enable()`. Use it with a consent banner. |
| `pageViews` | `true` | Send `page()` on every route change. `false` leaves page views to you. |
| `globalProps` | none | Props merged into every `page()` and `track()` call, such as the app name or build id. Props on the call win. |
| `debug` | development, unless [devtools](/packages/devtools) is installed | Print every call with `console.info('[analytics]', ...)` and print adapter errors with `console.warn`. |
| `events` | none | A type-only field that carries your event map. You never set it at run time. |

| Variable | Used for |
| --- | --- |
| `VITE_GA_MEASUREMENT_ID` | Your Google Analytics 4 measurement id, such as `G-ACME12345`. When set, the generated config adds the Google Analytics adapter. |
| `VITE_APP_NAME` | Already in your env. The generated config sends it as the `app` prop on every event. |

Variables that start with `VITE_` are bundled into the browser code. Measurement ids and public project keys are meant to be public; never put a secret API key in one.

## Track your first event

`kitr add` wrote `app/analytics.ts`. It lists every event the app sends, with the props each one carries:

```ts
// app/analytics.ts
import type { EventMap } from 'kitr/analytics'

/** Every event the app sends, with its props. `useAnalytics<AppEvents>()` checks names and props. */
export interface AppEvents extends EventMap {
  'sign-in.completed': { method: 'password' | 'oauth' }
  'project.created': { id: string }
}
```

In a component, get the analytics service with `useAnalytics()` from `kitr/analytics/react` and call `track()` after the thing happened:

```tsx
// app/features/projects/new-project-button.tsx
import { useAnalytics } from 'kitr/analytics/react'
import type { AppEvents } from '#app/analytics'

export function NewProjectButton({ onCreate }: { onCreate: () => Promise<{ id: string }> }) {
  const analytics = useAnalytics<AppEvents>()
  return (
    <button
      type="button"
      onClick={async () => {
        const project = await onCreate()
        analytics.track('project.created', { id: project.id })
      }}
    >
      New project
    </button>
  )
}
```

Render it on the projects page and click it. In development, with no adapter configured, the browser console shows:

```
[analytics] track project.created { app: 'acme', id: 'prj_42' }
```

The `app` prop comes from `globalProps` in `config/analytics.ts`. When [devtools](/packages/devtools) is not installed, the same line prints twice: once from `debug` logging and once from the console adapter. With devtools installed, it prints once and the call also appears in the Analytics panel.

Set `VITE_GA_MEASUREMENT_ID=G-ACME12345` in `.env`, restart the dev server, and the same click sends a `project.created` event to Google Analytics. No component changes.

## Declare your events

Add a line to `AppEvents` for every new event. Use `undefined` for an event without props:

```ts
// app/analytics.ts
import type { EventMap } from 'kitr/analytics'

export interface AppEvents extends EventMap {
  'sign-in.completed': { method: 'password' | 'oauth' }
  'project.created': { id: string }
  'invoice.paid': { invoiceId: string; amount: number; currency: 'USD' | 'EUR' }
  'team.invited': { teamId: string; role: 'admin' | 'member' }
  'upgrade.clicked': undefined
}
```

`useAnalytics<AppEvents>()` gives your editor the list of names and the props for each, so `analytics.track('inv` completes to `'invoice.paid'` and shows its props:

```tsx
// app/features/invoices/pay-button.tsx
import { useAnalytics } from 'kitr/analytics/react'
import type { AppEvents } from '#app/analytics'

export function PayButton({ invoiceId, amount }: { invoiceId: string; amount: number }) {
  const analytics = useAnalytics<AppEvents>()
  return (
    <button
      type="button"
      onClick={() => analytics.track('invoice.paid', { invoiceId, amount, currency: 'USD' })}
    >
      Pay {amount} USD
    </button>
  )
}
```

`track()` also has an untyped form, `track(event: string, props?)`, so TypeScript accepts any name and any props. A misspelt name such as `'invoce.paid'` compiles and is sent as a new event. Keep every name in `AppEvents` and pick it from autocomplete rather than typing it.

Name events `object.action` in the past tense (`project.created`, `invoice.paid`), the way the generated file does. Most analytics services group events by name, and one naming rule keeps their dashboards readable.

`defineEvents<AppEvents>()` ties the event map to a config object. It returns its input unchanged and exists for code that builds its own analytics instance:

```ts
// app/features/onboarding/analytics.ts
import { consoleAdapter, createAnalytics, defineEvents } from 'kitr/analytics'
import type { AppEvents } from '#app/analytics'

const config = defineEvents<AppEvents>()({ adapters: [consoleAdapter({ prefix: '[onboarding]' })] })

export const onboardingAnalytics = createAnalytics<AppEvents>(config)
```

## Track page views

The provider sends a page view for you. It renders a small tracker after the app mounts that reads the router from the container and calls `page()`:

- once for the page the visitor lands on, and
- again after every navigation that changes the path.

A change to the search or the hash alone (`/projects?sort=name`) is not a new page view. Each call carries the path and two props:

```ts
// What the tracker sends when Ada opens her projects page
analytics.page('/projects', { url: 'https://app.acme.com/projects', title: 'Projects · Acme' })
// adapters receive: ('/projects', { app: 'acme', url: 'https://app.acme.com/projects', title: 'Projects · Acme' })
```

The tracker needs the router that `createKitrRouter()` from [`kitr/router`](/packages/router) binds into the container. Without one, it sends nothing.

To send page views yourself, turn the automatic ones off:

```ts
// config/analytics.ts
import { defineConfig } from 'kitr/analytics'

export default defineConfig({
  adapters: [],
  pageViews: false,
})
```

Then call `page()` where you decide a page was seen, for example when a wizard step changes but the URL does not:

```tsx
// app/features/onboarding/step.tsx
import { useAnalytics } from 'kitr/analytics/react'
import { useEffect } from 'react'

export function OnboardingStep({ step }: { step: 'team' | 'project' | 'invite' }) {
  const analytics = useAnalytics()
  useEffect(() => {
    analytics.page(`/onboarding/${step}`, { title: `Onboarding: ${step}` })
  }, [analytics, step])
  return null
}
```

If you build the React tree by hand instead of through the provider, render `<TrackPageViews />` from `kitr/analytics/react` once inside it. It renders nothing and does the same work as the provider's tracker.

## Identify a signed-in user

After sign-in, tell the services who the visitor is, so later events join up with their earlier ones. Pass a stable id, never an email address:

```tsx
// app/features/auth/sign-in-form.tsx
import { useAnalytics } from 'kitr/analytics/react'
import type { AppEvents } from '#app/analytics'

export function useAfterSignIn() {
  const analytics = useAnalytics<AppEvents>()
  return (user: { id: string; plan: 'free' | 'team' }) => {
    analytics.identify(user.id, { plan: user.plan })
    analytics.track('sign-in.completed', { method: 'password' })
  }
}
```

Call the returned function when Grace's sign-in succeeds: `afterSignIn({ id: 'usr_grace', plan: 'team' })`. Google Analytics sets `user_id` and the `plan` user property, PostHog calls `posthog.identify('usr_grace', { plan: 'team' })`, and Plausible, which has no user profiles, ignores it. `identify()` does not add `globalProps`.

## Forget the user on sign-out

Call `reset()` when the visitor signs out, so the next person on a shared computer is not counted as them:

```tsx
// app/features/auth/sign-out-button.tsx
import { useAnalytics } from 'kitr/analytics/react'

export function SignOutButton({ onSignOut }: { onSignOut: () => Promise<void> }) {
  const analytics = useAnalytics()
  return (
    <button
      type="button"
      onClick={async () => {
        await onSignOut()
        analytics.reset()
      }}
    >
      Sign out
    </button>
  )
}
```

Google Analytics clears `user_id`, PostHog calls `posthog.reset()`, and adapters without a `reset` method skip it.

## Add props to every event

`globalProps` in `config/analytics.ts` are merged into every `page()` and `track()` call. Use them for facts about the build, not about the visitor:

```ts
// config/analytics.ts
import { defineConfig, plausible } from 'kitr/analytics'
import { env } from '#app/env'

export default defineConfig({
  adapters: [plausible({ domain: 'app.acme.com' })],
  globalProps: { app: env.VITE_APP_NAME, release: '2026.11.1' },
})
```

A prop on the call wins over a global prop with the same name: `track('project.created', { id: 'prj_42', release: 'canary' })` sends `release: 'canary'`.

## Track outside a component

Outside React, read the service from the container. In a store, a query hook or a provider, `app.container.use('analytics')` returns the same instance the components use:

```ts
// app/features/projects/create-project.ts
import type { Analytics } from 'kitr/analytics'
import type { KitrApp } from 'kitr/app'
import type { AppEvents } from '#app/analytics'

export async function createProject(app: KitrApp, name: string) {
  const response = await fetch('/api/projects', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ name }),
  })
  const project: { id: string } = await response.json()
  const analytics = app.container.use('analytics') as Analytics<AppEvents>
  analytics.track('project.created', { id: project.id })
  return project
}
```

Don't import `googleAnalytics()` or `window.gtag` into feature code to send an event. Go through the service, so consent, queuing and every other adapter still apply.

## Adapters

An adapter sends calls to one service. List as many as you like in `adapters`; every call goes to each of them in order. Each adapter loads its own script or client the first time tracking is enabled in the browser, never on the server.

| Adapter | Sends to | Script or client |
| --- | --- | --- |
| `googleAnalytics({ measurementId })` | Google Analytics 4 | Loads `gtag.js` for you. |
| `plausible({ domain, apiHost })` | Plausible, cloud or self-hosted | Loads `script.manual.js` for you. |
| `posthog(client, { apiKey })` | PostHog | You install `posthog-js` and pass it in. |
| `consoleAdapter({ prefix })` | The browser console | None. The development default. |
| `memoryAdapter()` | An array in memory | None. For tests. |

### Google Analytics

Nothing to install. `googleAnalytics()` injects the `gtag.js` script once and turns off gtag's own page views, so the router decides what a page view is.

```ts
// config/analytics.ts
import { defineConfig, googleAnalytics } from 'kitr/analytics'
import { env } from '#app/env'

export default defineConfig({
  adapters: env.VITE_GA_MEASUREMENT_ID
    ? [googleAnalytics({ measurementId: env.VITE_GA_MEASUREMENT_ID, debug: false })]
    : [],
})
```

Then set the id in `.env`:

```sh
VITE_GA_MEASUREMENT_ID=G-ACME12345
```

| Option | Default | Description |
| --- | --- | --- |
| `measurementId` | required | The `G-` id of your GA4 data stream. |
| `debug` | off | Sets gtag's `debug_mode`, so events show in GA's DebugView. |

`page()` becomes a `page_view` event with `page_path`, `page_location` and `page_title`. `track('project.created', { id })` becomes `gtag('event', 'project.created', { id })`. GA4 has its own rules for event names; check them in the [GA4 event reference](https://developers.google.com/analytics/devguides/collection/ga4/reference/events) before you settle on a naming scheme for an app that sends to GA.

### Plausible

Nothing to install. `plausible()` injects Plausible's manual script (`/js/script.manual.js`) once, with `data-domain` set to your site.

```ts
// config/analytics.ts
import { defineConfig, plausible } from 'kitr/analytics'

export default defineConfig({
  adapters: [plausible({ domain: 'app.acme.com' })],
})
```

For a self-hosted Plausible, point `apiHost` at it. A trailing slash is removed:

```ts
// config/analytics.ts
import { defineConfig, plausible } from 'kitr/analytics'

export default defineConfig({
  adapters: [plausible({ domain: 'app.acme.com', apiHost: 'https://stats.acme.com' })],
})
```

| Option | Default | Description |
| --- | --- | --- |
| `domain` | required | The site as registered in Plausible. |
| `apiHost` | `https://plausible.io` | Where the script is loaded from. |

`page()` sends a `pageview` with the full URL and your props as custom props. `track()` sends a custom event with props. Calls made before the script loads wait in Plausible's own queue. Plausible has no user profiles, so `identify()` and `reset()` do nothing. Create a goal in Plausible for each event name you want to count; see [custom event goals](https://plausible.io/docs/custom-event-goals).

### PostHog

Install the PostHog browser client, then pass it in. kitr does not import `posthog-js` itself, so it stays out of your bundle until you add it:

```sh
pnpm add posthog-js
```

```ts
// config/analytics.ts
import posthogJs from 'posthog-js'
import { defineConfig, posthog } from 'kitr/analytics'
import { env } from '#app/env'

export default defineConfig({
  adapters: env.VITE_POSTHOG_KEY
    ? [
        posthog(posthogJs, {
          apiKey: env.VITE_POSTHOG_KEY,
          apiHost: 'https://eu.i.posthog.com',
          config: { autocapture: false },
        }),
      ]
    : [],
})
```

Declare the key in `app/env.ts`:

```ts
// app/env.ts
import { createEnv, env as e } from 'kitr/env'

export const env = createEnv({
  public: {
    // ...
    VITE_GA_MEASUREMENT_ID: e.string({ optional: true }),
    VITE_POSTHOG_KEY: e.string({ optional: true }),
  },
  server: {},
})
```

Then set it in `.env`:

```sh
VITE_POSTHOG_KEY=phc_acme
```

| Option | Default | Description |
| --- | --- | --- |
| `apiKey` | required | Your PostHog project API key. |
| `apiHost` | `https://us.i.posthog.com` | Your PostHog region or proxy. |
| `config` | none | Any other `posthog.init()` options, merged last. |

The adapter calls `posthog.init(apiKey, { api_host, capture_pageview: false, ...config })`. Automatic page views are off so the router drives them; `page()` becomes a `$pageview` capture with `$current_url`. Any object with `init`, `capture`, `identify` and `reset` works as the client (the `PostHogLike` type). See the [posthog-js docs](https://posthog.com/docs/libraries/js) for `config` options.

### Console

`consoleAdapter()` prints each call with `console.info`. It is what the provider uses in development when `adapters` is empty. Add it yourself to see calls next to a real service, with a prefix to tell them apart:

```ts
// config/analytics.ts
import { consoleAdapter, defineConfig, plausible } from 'kitr/analytics'

export default defineConfig({
  adapters: [plausible({ domain: 'app.acme.com' }), consoleAdapter({ prefix: '[acme]' })],
})
```

```
[acme] page /projects { app: 'acme', url: 'https://app.acme.com/projects', title: 'Projects · Acme' }
[acme] track project.created { app: 'acme', id: 'prj_42' }
```

### Memory

`memoryAdapter()` records every call in its `calls` array as `{ type, args }`. Use it in tests; see [Testing](#testing).

## Wait for consent

In much of the world you need permission before tracking. Set `enabled: false` and every call waits in a queue instead of going out:

```ts
// config/analytics.ts
import { defineConfig, googleAnalytics } from 'kitr/analytics'
import { env } from '#app/env'

export default defineConfig({
  adapters: env.VITE_GA_MEASUREMENT_ID
    ? [googleAnalytics({ measurementId: env.VITE_GA_MEASUREMENT_ID })]
    : [],
  enabled: false,
})
```

When the visitor agrees, call `enable()`. It loads each adapter's script, then sends the queued calls in order:

```tsx
// app/components/tracking-choice.tsx
import { useAnalytics } from 'kitr/analytics/react'
import { useState } from 'react'

export function TrackingChoice() {
  const analytics = useAnalytics()
  const [answered, setAnswered] = useState(analytics.enabled)
  if (answered) return null
  return (
    <div role="dialog" aria-label="Tracking">
      <p>Acme counts page views to improve the app.</p>
      <button
        type="button"
        onClick={() => {
          void analytics.enable()
          setAnswered(true)
        }}
      >
        Allow
      </button>
      <button
        type="button"
        onClick={() => {
          analytics.disable()
          setAnswered(true)
        }}
      >
        No thanks
      </button>
    </div>
  )
}
```

`analytics.enabled` is a plain property, not React state, so the component keeps its own `answered` flag to re-render. This example does not remember the answer across visits; [consent](/packages/consent) stores it in a cookie.

What happens to each call:

- Before `enable()`, calls queue. The queue holds 100; later calls are dropped until you enable.
- `enable()` resolves once every adapter's `init()` has run, then the queue is sent. Calling it again does nothing.
- `disable()` empties the queue and stops sending. Calls made after it queue again and go out if `enable()` is called later.
- `analytics.enabled` tells you which state you are in.

The [consent](/packages/consent) package does all of this for you: it calls `enable()` when the visitor grants the `analytics` category and `disable()` when they withdraw it. With consent installed, never call `enable()` yourself; add `enabled: false` to `config/analytics.ts` and let the banner decide.

> **Warning**
> Without `enabled: false`, the provider enables analytics while the app boots, before any consent check runs. That loads `gtag.js` (or the Plausible or PostHog script), and the vendor may set cookies, even though [consent](/packages/consent) disables sending a moment later. Set `enabled: false` whenever you need consent first.

## Add an adapter at run time

`use()` adds an adapter after the app has started. If analytics is already enabled, the adapter's script loads at once; otherwise it loads on `enable()`. Use it for a service you only want for some visitors, such as session replay for Acme staff:

```tsx
// app/features/staff/staff-tools.tsx
import { posthog } from 'kitr/analytics'
import { useAnalytics } from 'kitr/analytics/react'
import posthogJs from 'posthog-js'
import { useEffect } from 'react'

export function StaffTools({ email }: { email: string }) {
  const analytics = useAnalytics()
  useEffect(() => {
    if (!email.endsWith('@acme.com')) return
    if (analytics.adapters.some((a) => a.name === 'posthog')) return
    analytics.use(posthog(posthogJs, { apiKey: 'phc_acme_staff' }))
  }, [analytics, email])
  return null
}
```

An added adapter only receives calls made after it was added. `analytics.adapters` lists every adapter by `name`; there is no way to remove one.

## Survive blocked scripts

Ad blockers block analytics scripts, and vendors have outages. Every adapter call runs inside a `try`, and a rejected promise from an adapter is caught, so `track()` never throws into your click handler and the other adapters still receive the call:

```ts
import { createAnalytics, memoryAdapter } from 'kitr/analytics'

const memory = memoryAdapter()
const analytics = createAnalytics({
  adapters: [
    { name: 'blocked', page: () => {}, track: () => Promise.reject(new Error('blocked')) },
    memory,
  ],
})
await analytics.enable()
analytics.track('project.created', { id: 'prj_42' })
// => no error; memory.calls has the track call
```

With `debug` on, each failure prints `[analytics] blocked Error: blocked` as a warning. In production `debug` is off and failures are silent.

## Use it on the server

During server rendering the provider still binds `analytics`, so components that call `useAnalytics()` render the same on both sides. Adapters never load their scripts on the server, because `init()` is skipped when there is no `window`, and the page view tracker runs in an effect, which the server never runs.

Call `track()` from event handlers and effects, never during render or in a route loader. On the server such a call still reaches the adapters, which have no script to deliver it: the console adapter prints it to the server log, and the Google Analytics and Plausible adapters push it onto a global queue that nothing reads. To record a server event, such as a paid invoice, write it from the controller to your database or a [job](/packages/jobs).

## Testing

Pass `memoryAdapter()` in config and assert on its `calls`. Each call is recorded as `{ type, args }`, with `globalProps` already merged in. This test renders the button from [Track your first event](#track-your-first-event) inside a test app and checks the event it sends:

```tsx
// app/features/projects/new-project-button.test.tsx
import { fireEvent, screen, waitFor } from '@testing-library/react'
import { memoryAdapter } from 'kitr/analytics'
import { analyticsProvider } from 'kitr/analytics/provider'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { describe, expect, it } from 'vitest'
import { NewProjectButton } from './new-project-button'

describe('NewProjectButton', () => {
  it('tracks project.created with the new id', async () => {
    const memory = memoryAdapter()
    const app = await createTestApp({
      providers: [analyticsProvider],
      config: { analytics: { adapters: [memory], globalProps: { app: 'acme' } } },
    })
    renderWithKitr(<NewProjectButton onCreate={async () => ({ id: 'prj_42' })} />, { app })

    fireEvent.click(screen.getByRole('button', { name: 'New project' }))

    await waitFor(() =>
      expect(memory.calls).toContainEqual({
        type: 'track',
        args: ['project.created', { app: 'acme', id: 'prj_42' }],
      }),
    )
  })
})
```

For code outside components, build an instance with `createAnalytics()` and no app at all. This one checks the consent queue:

```ts
// app/features/projects/analytics.test.ts
import { createAnalytics, memoryAdapter } from 'kitr/analytics'
import { expect, it } from 'vitest'

it('holds events until tracking is enabled', async () => {
  const memory = memoryAdapter()
  const analytics = createAnalytics({ adapters: [memory], enabled: false })

  analytics.track('project.created', { id: 'prj_42' })
  analytics.identify('usr_ada', { plan: 'team' })
  expect(memory.calls).toEqual([])

  await analytics.enable()
  expect(memory.calls).toEqual([
    { type: 'track', args: ['project.created', { id: 'prj_42' }] },
    { type: 'identify', args: ['usr_ada', { plan: 'team' }] },
  ])
})
```

The assertions you will write most:

| Assertion | Checks |
| --- | --- |
| `expect(memory.calls).toContainEqual({ type: 'track', args: ['invoice.paid', expect.objectContaining({ invoiceId: 'inv_7' })] })` | An event was sent with a prop, ignoring the others. |
| `expect(memory.calls.filter((c) => c.type === 'page')).toHaveLength(1)` | One page view. |
| `expect(memory.calls).toContainEqual({ type: 'reset', args: [] })` | Sign-out cleared the user. |
| `expect(analytics.enabled).toBe(false)` | Nothing goes out before consent. |

`createTestApp()` boots in the `test` mode, so the provider adds no console adapter and nothing is printed.

## Extend

An adapter is an object that implements `AnalyticsAdapter`. Only `name`, `page` and `track` are required:

```ts
// The interface, from kitr/analytics
export interface AnalyticsAdapter {
  name: string
  init?(): void | Promise<void>
  page(path: string, props?: EventProps & { url?: string; title?: string }): void
  track(event: string, props?: EventProps): void
  identify?(userId: string, traits?: EventProps): void
  reset?(): void
}
```

`init()` runs once, in the browser, the first time tracking is enabled. Load scripts and create clients there, not when the adapter is created, so nothing loads before consent. The other methods should be quick and must not throw; the service catches errors, but an adapter that throws on every call hides real problems.

This adapter sends Acme's events to its own endpoint with `navigator.sendBeacon`, which survives the page closing:

```ts
// app/analytics/acme-adapter.ts
import type { AnalyticsAdapter, EventProps } from 'kitr/analytics'

export function acmeAdapter(options: { endpoint: string }): AnalyticsAdapter {
  let userId: string | undefined
  const send = (type: string, name: string, props?: EventProps) => {
    const body = JSON.stringify({ type, name, props, userId, at: new Date().toISOString() })
    if (!navigator.sendBeacon(options.endpoint, body)) {
      void fetch(options.endpoint, { method: 'POST', body, keepalive: true })
    }
  }
  return {
    name: 'acme',
    page: (path, props) => send('page', path, props),
    track: (event, props) => send('track', event, props),
    identify(id, traits) {
      userId = id
      send('identify', id, traits)
    },
    reset() {
      userId = undefined
    },
  }
}
```

Register it in config like any built-in adapter:

```ts
// config/analytics.ts
import { defineConfig } from 'kitr/analytics'
import { acmeAdapter } from '#app/analytics/acme-adapter'

export default defineConfig({
  adapters: [acmeAdapter({ endpoint: 'https://app.acme.com/api/events' })],
})
```

See [`AnalyticsAdapter`](/packages/analytics/api#analyticsadapter) in the API reference.

## Devtools

With [devtools](/packages/devtools) installed, the provider adds a devtools adapter that copies every call into the log under the `analytics` channel, and an Analytics panel. The panel shows whether tracking is enabled or still queued, the names of the active adapters, and the last 200 calls with their props. Its actions are Enable (consent given), Disable and Clear events, and each one is also in the command palette.

## Next steps

- [API reference](/packages/analytics/api) for every export and type.
- [Consent](/packages/consent) to hold analytics until visitors agree.
- [Devtools](/packages/devtools) to watch every call while you build.
- [Monitoring](/packages/monitoring) to report errors rather than usage.
- [Router](/packages/router) for the navigations that become page views.


# API routes API

Source: https://kitr.dev/packages/api/api

## defineRoutes

```ts
const routes = defineRoutes((router) => router.get(...).group(...))
type AppRoutes = typeof routes.$types
```

### Router methods

| Method | Description |
| --- | --- |
| `get / post / put / patch / delete(path, handler, options?)` | Add a route. `handler` is `(ctx) => body` or `[Controller, 'method']`. |
| `resource(name, Controller)` | `index`, `store`, `show`, `update`, `destroy` under `/<name>`. |
| `group({ prefix?, middleware?, as? }, (router) => router)` | Share a prefix, middleware and name prefix. |
| `toJSON()` | Route names, methods and paths, for `registerRoutes`. |

### Route options

| Option | Description |
| --- | --- |
| `name` | Used by the client (`api.projects.show`) and `router.url()`. |
| `validate` | `{ params?, query?, body? }` Standard Schemas. |
| `middleware` | Extra middleware for this route. |
| `meta` | `summary`, `description`, `tags`, `deprecated`, emitted into OpenAPI. |

## HttpContext

```ts
interface HttpContext<Params, Query, Body> {
  params: Params
  query: Query
  body: Body
  request: KitrRequest   // method, url, header(name)
  response: KitrResponse // status(code), header(name, value)
  locals: Record<string, unknown>
  logger: Logger
  requestId: string
  app: KitrApp
  validate(schema, source?: 'body' | 'query' | 'params'): Promise<Output>
}
```

## Middleware

```ts
defineMiddleware(async (ctx, next) => { ...; return next() })
cors({ origin?, methods?, headers?, credentials?, maxAge? })
rateLimit({ max?, windowMs?, key? })
requireJson()
compose([a, b, c])
```

## Mounting

```ts
mountRoutes(server: KitrServer, routes: Router, base = '/'): KitrServer
toH3(routes, app, { h3? }): H3
```

## toOpenApi

```ts
toOpenApi(routes, { title?, version?, description?, servers?, schemaToJson? }): Promise<OpenAPIDocument>
```

## Configuration

```ts
// config/api.ts
defineConfig({
  prefix?: string,
  openapi?: { path?: string; title?: string; version?: string; description?: string },
  client?: { path?: string },
})
```

Read by `kitr api:sync`.

## kitr/api/client

```ts
createApiClient<AppRoutes>({
  baseUrl: string,
  fetch?: (request: Request) => Promise<Response>, // e.g. server.fetch in tests
  headers?: () => HeadersInit | Promise<HeadersInit>,
  getToken?: () => string | null | Promise<...>,
  credentials?: RequestCredentials,
})
```

Each endpoint is callable and has:

| Member | Description |
| --- | --- |
| `(input?)` | Call it. Input is `{ params?, query?, body? }`, typed per route. |
| `.query()` | A query contract for `defineQuery`. |
| `.mutation({ effects? })` | A mutation contract for `defineMutation`. |
| `.key(input?)` | The cache key: `['api', routeName, params, query]`. |
| `.url(input?)` | The full URL. |
| `.method`, `.path` | From the route. |

Errors reject with a `KitrError`.


# API routes

Source: https://kitr.dev/packages/api

A mobile app that lists orders, a partner that posts invoices, a webhook from your payment provider: each needs JSON endpoints with clear inputs and clear errors. `kitr/api` gives you a router, controllers, validation and middleware in the style of [AdonisJS](https://docs.adonisjs.com/guides/basics/routing), and a client for the browser that knows every route's inputs and outputs without generating any code.

It runs on [h3](https://h3.dev) through [Server](/packages/server), inside a TanStack Start app or as a standalone backend with no React at all. Validation takes any [Standard Schema](https://standardschema.dev) library, such as zod, valibot or arktype, and `kitr api:sync` writes an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) document from the same routes.

Routes and controllers run on the server. The typed client (`kitr/api/client`) runs in the browser, on the server and in tests.

The examples on this page build the Acme orders API at `app.acme.com/api`: list, create and show orders, with Ada, Grace and Linus as customers.

## When to use it

Use API routes for anything outside your own React UI: mobile apps, partners, webhooks, scripts, or whenever you want REST URLs and an OpenAPI document.

For functions only your own UI calls, use [Actions](/packages/actions): no URLs to design, and the same validation and error shape. Both can live in one app.

## Install

```sh
kitr add api
```

What `kitr add api` does:

- Runs the [Server](/packages/server) recipe first if it is missing, which also adds [Logger](/packages/logger).
- Installs `@kitr/api` and adds it to `packages` in `kitrrc.ts`.
- Writes `config/api.ts` (shown under Configure) and adds it to `config/index.ts`.
- Writes `server/routes.ts`, with one `GET /api/health` route behind `cors()`.
- Writes `server/controllers/health_controller.ts`, the controller that route calls.
- When `server/main.ts` exists without routes, adds `import { mountRoutes } from 'kitr/api'`, `import { routes } from './routes'` and `mountRoutes(server, routes)` to it.
- In a React project, writes `app/api/client.ts`, the typed client.
- Adds a `kitr: api` section to `AGENTS.md`.

The generated routes file:

```ts
// server/routes.ts
import { cors, defineRoutes } from 'kitr/api'
import HealthController from '#server/controllers/health_controller'

export const routes = defineRoutes((router) =>
  router.group({ prefix: '/api', middleware: [cors()] }, (api) =>
    api.get('/health', [HealthController, 'show'], { name: 'health' }),
    // api.resource('projects', () => import('#server/controllers/projects_controller'))
  ),
)

/** Pass to createApiClient<AppRoutes>() on the client. */
export type AppRoutes = typeof routes.$types
```

The generated controller:

```ts
// server/controllers/health_controller.ts
import type { HttpContext } from 'kitr/api'

export default class HealthController {
  async show({ requestId }: HttpContext) {
    return { ok: true, requestId }
  }
}
```

API routes need a server platform to run on. If the project has none, add one with `kitr add server api`. The `fullstack`, `server`, `saas`, `site` and `realtime` kits include API routes already.

`kitr remove api` removes `@kitr/api` from `package.json` and `kitrrc.ts`, deletes `config/api.ts` and drops the `AGENTS.md` section. It keeps `server/routes.ts`, your controllers and `app/api/client.ts`, and lists the files that still import `kitr/api`.

## Configure

`kitr add api` writes this file, with your package name in the title:

```ts
// config/api.ts
import { defineConfig } from 'kitr/api'

export default defineConfig({
  prefix: '/api',
  openapi: { path: 'openapi.json', title: 'acme API', version: '0.1.0' },
})
```

| Option | Default | Description |
| --- | --- | --- |
| `prefix` | none | Documents the prefix your routes share. The router does not read it: set the prefix with `router.group({ prefix: '/api' })` in `server/routes.ts`. |
| `openapi.path` | `'openapi.json'` | Where `kitr api:sync` writes the OpenAPI document. |
| `openapi.title` | `'<package name> API'` | `info.title` in the document. |
| `openapi.version` | `package.json` version | `info.version` in the document. |
| `openapi.description` | none | Declared for `info.description`. `kitr api:sync` does not read it yet; pass `description` to `toOpenApi()` instead. |
| `client.path` | `'app/api/client.ts'` | Declared for the client file. `kitr api:sync` does not read it yet. |

`kitr api:sync` reads `openapi.path`, `openapi.title` and `openapi.version` from the file's text, so keep them as plain string literals. API routes add no environment variables.

## Build your first endpoint

Write a controller for orders. Each method receives the request context and returns the response body:

```ts
// server/controllers/orders_controller.ts
import type { HttpContext } from 'kitr/api'
import { KitrError } from 'kitr/app'

export interface Order {
  id: string
  customer: string
  total: number
  status: 'open' | 'paid'
}

const orders = new Map<string, Order>([
  ['ord_1042', { id: 'ord_1042', customer: 'Ada', total: 129, status: 'open' }],
])

export default class OrdersController {
  async index() {
    return [...orders.values()]
  }

  async show({ params }: HttpContext<{ id: string }>) {
    const order = orders.get(params.id)
    if (!order) throw KitrError.notFound('Order')
    return order
  }
}
```

Register it in the routes file:

```ts
// server/routes.ts
import { cors, defineRoutes } from 'kitr/api'
import HealthController from '#server/controllers/health_controller'
import OrdersController from '#server/controllers/orders_controller'

export const routes = defineRoutes((router) =>
  router.group({ prefix: '/api', middleware: [cors()] }, (api) =>
    api
      .get('/health', [HealthController, 'show'], { name: 'health' })
      .resource('orders', OrdersController),
  ),
)

export type AppRoutes = typeof routes.$types
```

Start the server with `kitr dev api` (or `kitr dev` in a React app) and ask for an order:

```sh
curl http://localhost:3001/api/orders/ord_1042
```

```json
{ "id": "ord_1042", "customer": "Ada", "total": 129, "status": "open" }
```

`resource('orders', ...)` registered `GET /api/orders` and `GET /api/orders/:id` because the controller has `index` and `show`. An unknown id answers `404` with `{ "code": "NOT_FOUND", "message": "Order not found", "status": 404 }`.

## Define routes

The router has one method per HTTP verb. Each takes a path, a handler and options, and returns the router so you can chain:

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'
import InvoicesController from '#server/controllers/invoices_controller'

export const routes = defineRoutes((router) =>
  router
    .get('/api/invoices', [InvoicesController, 'index'], { name: 'invoices.index' })
    .post('/api/invoices', [InvoicesController, 'store'], { name: 'invoices.store' })
    .put('/api/invoices/:id', [InvoicesController, 'replace'], { name: 'invoices.replace' })
    .patch('/api/invoices/:id', [InvoicesController, 'update'], { name: 'invoices.update' })
    .delete('/api/invoices/:id', [InvoicesController, 'destroy'], { name: 'invoices.destroy' })
    .get('/api/ping', () => ({ pong: true }), { name: 'ping' }),
)

export type AppRoutes = typeof routes.$types
```

A handler is either a `[Controller, 'method']` pair or a function that takes the context. TypeScript checks that the method exists on the controller.

| Route option | Description |
| --- | --- |
| `name` | The name the client calls (`api.invoices.index()`) and `router.url()` looks up. Dots make nested client properties. Without a name, the route is called `'GET /api/ping'`. |
| `validate` | Schemas for `params`, `query` and `body`. See "Validate input". |
| `middleware` | Middleware for this route only, after the group's. |
| `meta` | `summary`, `description`, `tags` and `deprecated`, copied into the OpenAPI document. |

Path parameters start with `:` and arrive as strings in `ctx.params`. A trailing `*` matches the rest of the path. `router.any(path, handler)` registers one handler for every method; it is not part of the typed client.

Give every route you call from the client a `name`. Names are stable when paths change, and they become the query keys in the client.

## Group routes

`router.group()` shares a prefix, middleware and a name prefix across routes:

```ts
// server/routes.ts
import { cors, defineRoutes } from 'kitr/api'
import OrdersController from '#server/controllers/orders_controller'
import TeamsController from '#server/controllers/teams_controller'
import { audit } from '#app/middleware/audit'

export const routes = defineRoutes((router) =>
  router.group({ prefix: '/api', middleware: [cors()] }, (api) =>
    api
      .resource('orders', OrdersController)
      .group({ prefix: '/admin', middleware: [audit], as: 'admin' }, (admin) =>
        admin.resource('teams', TeamsController),
      ),
  ),
)

export type AppRoutes = typeof routes.$types
```

| Group option | Effect |
| --- | --- |
| `prefix` | Joined onto every path inside: `/api` + `/admin` + `/teams` is `/api/admin/teams`. |
| `middleware` | Runs before every route inside, outer groups first. |
| `as` | Prefixes every name inside: `teams.index` becomes `admin.teams.index`, called as `api.admin.teams.index()`. |

`group('/api', ...)` with a string is short for `{ prefix: '/api' }`. `router.use(audit)` adds middleware to every route registered after the call, not before it.

## Create a resource

`resource(name, Controller)` registers the five REST routes for the methods the controller has, and names them `<name>.<action>`:

| Method | Path | Controller method | Route name | Client call |
| --- | --- | --- | --- | --- |
| GET | `/orders` | `index` | `orders.index` | `api.orders.index()` |
| POST | `/orders` | `store` | `orders.store` | `api.orders.store({ body })` |
| GET | `/orders/:id` | `show` | `orders.show` | `api.orders.show({ params: { id } })` |
| PATCH | `/orders/:id` | `update` | `orders.update` | `api.orders.update({ params, body })` |
| DELETE | `/orders/:id` | `destroy` | `orders.destroy` | `api.orders.destroy({ params })` |

Narrow it with options:

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'
import InvoicesController from '#server/controllers/invoices_controller'
import ProjectsController from '#server/controllers/projects_controller'
import { audit } from '#app/middleware/audit'

export const routes = defineRoutes((router) =>
  router.group('/api', (api) =>
    api
      .resource('invoices', InvoicesController, { only: ['index', 'show'] })
      .resource('projects', ProjectsController, {
        except: ['destroy'],
        param: 'projectId',
        middleware: [audit],
      }),
  ),
)

export type AppRoutes = typeof routes.$types
```

`param: 'projectId'` makes the paths `/api/projects/:projectId`, so the controller reads `params.projectId`.

## Load controllers lazily

Pass a function that imports the controller instead of the class. The file loads on the first request, which keeps server start-up fast when there are many controllers:

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'

export const routes = defineRoutes((router) =>
  router.group('/api', (api) =>
    api
      .resource('orders', () => import('#server/controllers/orders_controller'))
      .get('/orders/:id/receipt', [() => import('#server/controllers/receipts_controller'), 'show'], {
        name: 'orders.receipt',
      }),
  ),
)

export type AppRoutes = typeof routes.$types
```

A lazy controller can't be inspected when routes are defined, so `resource()` registers all five routes. Calling a method the controller doesn't have answers `404` with `Controller method OrdersController.update not found`.

## Write a controller

A controller is a plain class with a default export. `kitr make:controller orders --resource` writes one with all five methods. Each method receives an `HttpContext`; type its three parameters for `params`, `query` and `body`:

```ts
// server/controllers/orders_controller.ts
import type { HttpContext } from 'kitr/api'
import { KitrError } from 'kitr/app'
import { z } from 'zod'

const createOrder = z.object({
  customer: z.string().min(2),
  total: z.number().positive(),
})
const updateOrder = createOrder.partial()

export interface Order {
  id: string
  customer: string
  total: number
  status: 'open' | 'paid'
}

const orders = new Map<string, Order>([
  ['ord_1042', { id: 'ord_1042', customer: 'Ada', total: 129, status: 'open' }],
])

export default class OrdersController {
  static validation = {
    store: { body: createOrder },
    update: { body: updateOrder },
  }

  async index({ query }: HttpContext) {
    const status = typeof query.status === 'string' ? query.status : undefined
    return [...orders.values()].filter((order) => !status || order.status === status)
  }

  async show({ params }: HttpContext<{ id: string }>) {
    const order = orders.get(params.id)
    if (!order) throw KitrError.notFound('Order')
    return order
  }

  async store({ body, response, logger }: HttpContext<{}, {}, z.infer<typeof createOrder>>) {
    const order: Order = { id: `ord_${1042 + orders.size}`, status: 'open', ...body }
    orders.set(order.id, order)
    logger.info('order created', { id: order.id })
    response.status(201)
    return order
  }

  async update({ params, body }: HttpContext<{ id: string }, {}, z.infer<typeof updateOrder>>) {
    const order = orders.get(params.id)
    if (!order) throw KitrError.notFound('Order')
    const updated = { ...order, ...body }
    orders.set(order.id, updated)
    return updated
  }

  async destroy({ params }: HttpContext<{ id: string }>) {
    orders.delete(params.id)
  }
}
```

The context carries everything about the request:

| Field | What it holds |
| --- | --- |
| `params` | Path parameters, validated when a `params` schema is set. |
| `query` | Query string values (`string` or `string[]`), validated when a `query` schema is set. |
| `body` | The parsed body on `POST`, `PUT` and `PATCH`, validated when a `body` schema is set. |
| `request` | Headers, URL, IP and the raw body. See "Read the request". |
| `response` | Status, headers, redirects and raw responses. See "Shape the response". |
| `locals` | Values set by middleware. [Auth](/packages/auth) sets `user` and `can`. |
| `logger` | The request's logger, which adds the request id. |
| `requestId` | The request id from [Server](/packages/server). |
| `app` | The request-scoped app: `app.container.use('db')`. |
| `event` | The underlying h3 event. |
| `validate(schema, source)` | Validates `body`, `query` or `params` on demand. |

kitr creates one instance of each controller class and reuses it for every request. Don't store request data on `this`; keep it in local variables or `ctx.locals`.

## Validate input

Declare schemas per controller method in `static validation`. kitr validates before the method runs, and the typed client picks up the same types:

```ts
// server/controllers/orders_controller.ts
// ...
export default class OrdersController {
  static validation = {
    store: { body: createOrder },
    update: { body: updateOrder },
  }
  // ...
}
```

A request that fails gets `422` with every problem at once:

```sh
curl -X POST http://localhost:3001/api/orders \
  -H 'content-type: application/json' \
  -d '{"customer":"A","total":-1}'
```

```json
{
  "code": "VALIDATION",
  "message": "Validation failed",
  "status": 422,
  "fieldErrors": {
    "customer": ["Too small: expected string to have >=2 characters"],
    "total": ["Too small: expected number to be >0"]
  }
}
```

[Forms](/packages/forms) puts `fieldErrors` on the matching fields. The messages come from your schema library.

For function handlers, pass `validate` in the route options. Schemas for `params` and `query` also convert values, so `ctx.query.page` below is a number:

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'
import { z } from 'zod'

const invoicePage = z.object({ page: z.coerce.number().int().min(1).default(1) })

export const routes = defineRoutes((router) =>
  router.get('/api/invoices', ({ query }) => ({ page: query.page }), {
    name: 'invoices.index',
    validate: { query: invoicePage },
  }),
)

export type AppRoutes = typeof routes.$types
```

`GET /api/invoices?page=2` answers `{ "page": 2 }`; `?page=0` answers `422` with `{ "page": ["Too small: expected number to be >=1"] }`.

When the shape depends on the request, validate inside the handler with `ctx.validate()`. It throws the same `422`:

```ts
// server/controllers/invoices_controller.ts
import type { HttpContext } from 'kitr/api'
import { z } from 'zod'

const refund = z.object({ amount: z.number().positive(), reason: z.string() })

export default class InvoicesController {
  async refund(ctx: HttpContext<{ id: string }>) {
    const input = await ctx.validate(refund, 'body')
    return { invoice: ctx.params.id, refunded: input.amount }
  }
}
```

Validators set in route options take precedence over `static validation`. Without any validator, `body` is the raw parsed body on writes and `undefined` on reads.

## Read the request

`ctx.request` wraps the incoming request:

```ts
// server/controllers/webhooks_controller.ts
import type { HttpContext } from 'kitr/api'

export default class WebhooksController {
  async payment({ request, logger }: HttpContext) {
    const signature = request.header('x-acme-signature')
    const raw = await request.raw()
    logger.info('payment webhook', {
      ip: request.ip(),
      path: request.url.pathname,
      tags: request.qs().tag,
      signed: Boolean(signature),
    })
    return { received: true, type: (raw as { type?: string }).type }
  }
}
```

| Member | Returns |
| --- | --- |
| `method` | `'POST'` |
| `url` | A `URL` for the request. |
| `headers` | The `Headers` object. |
| `header(name)` | One header value, or `null`. |
| `ip()` | The client IP, or `undefined` when the runtime doesn't expose it. |
| `qs()` | Raw query values; repeated keys become arrays: `?tag=a&tag=b` gives `{ tag: ['a', 'b'] }`. |
| `raw()` | The body parsed by content type (JSON, form or text). Reading it twice returns the same value. |
| `native` | The web `Request`. |

Malformed JSON answers `400` with `{ "code": "BAD_REQUEST", "message": "Could not read request body: ..." }`, not a `500`.

## Shape the response

Whatever the handler returns becomes the JSON body with status `200`. Use `ctx.response` to change that:

```ts
// server/controllers/orders_controller.ts
import type { HttpContext } from 'kitr/api'

export default class OrdersController {
  async store({ response }: HttpContext) {
    response.status(201).header('location', '/api/orders/ord_1043')
    return { id: 'ord_1043', customer: 'Grace', total: 480, status: 'open' }
  }

  async legacy({ response }: HttpContext) {
    return response.redirect('/api/orders', 301)
  }

  async export({ response }: HttpContext) {
    return response.json({ queued: true }, { status: 202, headers: { 'x-export-id': 'exp_7' } })
  }

  async archive({ response }: HttpContext) {
    return response.noContent()
  }
}
```

| Method | Effect |
| --- | --- |
| `status(code)` | Sets the status for the returned body. Chainable. |
| `header(name, value)` | Sets a response header. Chainable. |
| `redirect(location, status = 302)` | Returns a redirect response. |
| `json(data, init)` | Returns a JSON `Response` with your status and headers. |
| `noContent()` | Returns an empty `204`. |

A handler that returns `undefined` or `null` answers with an empty body: `204`, or the status you set with `response.status()`. You can also return any web `Response` directly, such as a file stream.

## Return errors

Throw a `KitrError` from `kitr/app` to answer with an error. The status follows the code:

```ts
// server/controllers/invoices_controller.ts
import type { HttpContext } from 'kitr/api'
import { KitrError } from 'kitr/app'

export default class InvoicesController {
  async pay({ params }: HttpContext<{ id: string }>) {
    if (params.id === 'INV-1042') throw new KitrError('CONFLICT', 'Invoice INV-1042 is already paid')
    if (params.id.startsWith('draft')) throw KitrError.forbidden('Draft invoices cannot be paid')
    throw KitrError.notFound('Invoice')
  }
}
```

```json
{ "code": "CONFLICT", "message": "Invoice INV-1042 is already paid", "status": 409 }
```

Anything else that is thrown becomes `INTERNAL` with status `500`, and in production its message is replaced with `Internal server error`. [Server](/packages/server) logs every `5xx` with the request id.

## Write middleware

Middleware is a function of the context and `next`. Call `next()` to run the rest of the chain and return its result; return without calling it to answer early:

```ts
// app/middleware/audit.ts
import { defineMiddleware } from 'kitr/api'

export const audit = defineMiddleware(async (ctx, next) => {
  const started = performance.now()
  const result = await next()
  ctx.logger.info('audited', {
    path: ctx.request.url.pathname,
    durationMs: Math.round(performance.now() - started),
  })
  return result
})
```

`kitr make:middleware audit` writes this skeleton in `app/middleware/audit.ts`. Attach middleware to a group, a resource or one route:

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'
import InvitesController from '#server/controllers/invites_controller'
import { audit } from '#app/middleware/audit'
import { requireTeam } from '#app/middleware/require_team'

export const routes = defineRoutes((router) =>
  router.group({ prefix: '/api', middleware: [audit] }, (api) =>
    api.post('/teams/:teamId/invites', [InvitesController, 'store'], {
      name: 'invites.store',
      middleware: [requireTeam],
    }),
  ),
)

export type AppRoutes = typeof routes.$types
```

Pass data to the handler through `ctx.locals`, and stop a request by throwing a `KitrError`:

```ts
// app/middleware/require_team.ts
import { defineMiddleware } from 'kitr/api'
import { KitrError } from 'kitr/app'

export const requireTeam = defineMiddleware(async (ctx, next) => {
  const teamId = ctx.request.header('x-acme-team')
  if (!teamId) throw new KitrError('BAD_REQUEST', 'Missing x-acme-team header')
  ctx.locals.teamId = teamId
  return next()
})
```

Middleware runs outer to inner: group middleware first, then route middleware, then the handler, and back out in reverse. Calling `next()` twice throws `[kitr/api] next() called more than once`. `compose([a, b])` combines several middleware into one.

## Allow cross-origin requests

`cors()` answers browser preflight requests and sets the CORS headers. The generated routes file puts it on the `/api` group with defaults that allow any origin:

```ts
// server/routes.ts
import { cors, defineRoutes } from 'kitr/api'
import OrdersController from '#server/controllers/orders_controller'

export const routes = defineRoutes((router) =>
  router.group(
    {
      prefix: '/api',
      middleware: [cors({ origin: ['https://app.acme.com', 'https://admin.acme.com'], credentials: true })],
    },
    (api) => api.resource('orders', OrdersController),
  ),
)

export type AppRoutes = typeof routes.$types
```

| Option | Default | Description |
| --- | --- | --- |
| `origin` | `'*'` | `'*'`, one origin, a list, or a function `(origin) => boolean`. With `'*'` and `credentials`, the request's origin is echoed. |
| `methods` | `GET, POST, PUT, PATCH, DELETE, OPTIONS` | `access-control-allow-methods` on preflight. |
| `headers` | `Content-Type, Authorization` | `access-control-allow-headers` on preflight. |
| `credentials` | `false` | Sends `access-control-allow-credentials: true`, needed for cookies. |
| `maxAge` | `600` | Seconds a browser may cache the preflight. |

A preflight `OPTIONS /api/orders` answers `204` with the allow headers. kitr registers the `OPTIONS` route for every route behind `cors()`, so you don't write one.

> **Warning**
> `origin: '*'` with `credentials: true` echoes any origin, so any site can make signed-in requests to your API. With cookies, list your origins.

## Rate limit a route

`rateLimit()` counts requests per client IP in a window and answers `429` past the limit:

```ts
// server/routes.ts
import { defineRoutes, rateLimit } from 'kitr/api'
import InvitesController from '#server/controllers/invites_controller'

export const routes = defineRoutes((router) =>
  router.post('/api/invites', [InvitesController, 'store'], {
    name: 'invites.store',
    middleware: [
      rateLimit({ max: 5, windowMs: 60_000, key: (ctx) => ctx.request.header('x-acme-team') ?? 'anonymous' }),
    ],
  }),
)

export type AppRoutes = typeof routes.$types
```

| Option | Default | Description |
| --- | --- | --- |
| `max` | `100` | Requests allowed per key per window. |
| `windowMs` | `60000` | Window length in milliseconds. |
| `key` | client IP | Function from the context to a bucket key, such as a team or user id. |

Every response carries `ratelimit-limit`, `ratelimit-remaining` and `ratelimit-reset` (seconds). The sixth request in a minute gets `{ "code": "RATE_LIMITED", "message": "Too many requests", "status": 429 }`.

The counters live in the process's memory. With several server instances behind a load balancer, each counts on its own, so the real limit is `max` times the number of instances. For one limit across instances, use the rate limiter in [Shield](/packages/shield), which takes a shared `store`.

## Require JSON bodies

`requireJson()` rejects `POST`, `PUT` and `PATCH` requests whose `content-type` is not `application/json`, with `400` and `Expected application/json`. Reads pass through:

```ts
// server/routes.ts
import { defineRoutes, requireJson } from 'kitr/api'
import OrdersController from '#server/controllers/orders_controller'

export const routes = defineRoutes((router) =>
  router.group({ prefix: '/api', middleware: [requireJson()] }, (api) =>
    api.resource('orders', OrdersController),
  ),
)

export type AppRoutes = typeof routes.$types
```

## Call the API from the browser

In a React project, `kitr add api` writes the client:

```ts
// app/api/client.ts
import { createApiClient } from 'kitr/api/client'
import type { AppRoutes } from '#server/routes'

/** Typed, no codegen: route names, params, bodies and outputs come from the router. */
export const api = createApiClient<AppRoutes>({ baseUrl: typeof window === 'undefined' ? `http://localhost:${process.env.PORT ?? 3000}` : '' })
```

Only the type is imported from `server/routes.ts`, so no server code reaches the browser bundle. The client also needs the runtime route table, which maps names such as `orders.show` to a method and path. Generate it and register it once:

```sh
kitr api:sync
```

```ts
// app/api/client.ts
import { createApiClient, registerRoutes } from 'kitr/api/client'
import type { AppRoutes } from '#server/routes'
import { routeTable } from './routes.gen'

export const api = createApiClient<AppRoutes>({
  baseUrl: typeof window === 'undefined' ? `http://localhost:${process.env.PORT ?? 3000}` : '',
})
registerRoutes(api, [...routeTable])
```

Without a registered table, using a named route such as `api.orders.show` throws a `KitrError` with code `INTERNAL` and the message `[kitr/api] Unknown route "orders.show"...`, which tells you to register the routes. Run `kitr api:sync` again whenever you add or rename a route. On the server you can register straight from the router with `registerRoutes(api, routes.toJSON())`.

Every call is checked against the route:

```ts
// app/features/orders/load.ts
import { api } from '#app/api/client'

const orders = await api.orders.index()
// => [{ id: 'ord_1042', customer: 'Ada', total: 129, status: 'open' }]

const order = await api.orders.show({ params: { id: 'ord_1042' } })
// => { id: 'ord_1042', customer: 'Ada', total: 129, status: 'open' }

const created = await api.orders.store({ body: { customer: 'Grace', total: 480 } })
// => { id: 'ord_1043', status: 'open', customer: 'Grace', total: 480 }

await api.orders.store({ body: { customer: 'Grace' } })
// type error: property 'total' is missing
```

The input object has up to three keys: `params` (required when the path has parameters), `query` (values are stringified, `undefined` is dropped) and `body` (sent as JSON on everything but `GET` and `HEAD`). The return type is whatever the controller method returns. A `204` resolves to `undefined`.

Each endpoint also exposes helpers:

```ts
// app/features/orders/links.ts
import { api } from '#app/api/client'

api.orders.show.url({ params: { id: 'ord_1042' } })
// => '/api/orders/ord_1042'
api.orders.show.key({ params: { id: 'ord_1042' } })
// => ['api', 'orders.show', { id: 'ord_1042' }, {}]
api.orders.show.method
// => 'GET'
api.orders.show.path
// => '/api/orders/:id'
```

| Client option | Description |
| --- | --- |
| `baseUrl` | Prepended to every path. `''` in the browser calls the same origin. |
| `fetch` | Custom fetch: a test fake, or `server.fetch` for in-process calls. |
| `headers` | Function returning headers for every request; may be async. |
| `getToken` | Function returning a bearer token; sent as `authorization: Bearer <token>` when it returns one. |
| `credentials` | Passed to `fetch`: `'include'` sends cookies cross-origin. |

## Use endpoints with TanStack Query

Every endpoint produces [Query](/packages/query) contracts. `query()` uses the endpoint's key and fetch, and `mutation()` takes cache effects:

```tsx
// app/features/orders/orders_page.tsx
import { defineMutation, defineQuery, useKitrMutation, useSuspenseQuery } from 'kitr/query'
import { api } from '#app/api/client'

const ordersQuery = defineQuery(api.orders.index.query())
const createOrder = defineMutation(
  api.orders.store.mutation({ effects: { invalidate: [['api', 'orders.index']] } }),
)

export function OrdersPage() {
  const { data: orders } = useSuspenseQuery(ordersQuery.options({}))
  const create = useKitrMutation(createOrder)
  return (
    <section>
      <ul>
        {orders.map((order) => (
          <li key={order.id}>
            {order.customer}: {order.total}
          </li>
        ))}
      </ul>
      <button type="button" onClick={() => create.mutate({ body: { customer: 'Linus', total: 75 } })}>
        New order for Linus
      </button>
    </section>
  )
}
```

The query key is `['api', '<route name>', params, query]`, so `invalidate: [['api', 'orders.index']]` refetches every orders list after Linus's order is created. In a route loader, call `context.queryClient.ensureQueryData(ordersQuery.options({}))` so the server and client fetch once.

## Handle errors on the client

Failed calls reject with a `KitrError` that carries the server's code, status and field errors:

```ts
// app/features/orders/create.ts
import { KitrError } from 'kitr/app'
import { api } from '#app/api/client'

try {
  await api.orders.store({ body: { customer: 'A', total: -1 } })
} catch (error) {
  if (error instanceof KitrError && error.code === 'VALIDATION') {
    console.log(error.fieldErrors)
    // => { customer: ['Too small: expected string to have >=2 characters'], total: ['Too small: expected number to be >0'] }
  }
}
```

| Response | Rejects with |
| --- | --- |
| A kitr error body | The same `code`, `message`, `status`, `fieldErrors` and `data`. |
| Another error body | A code from the status (`403` is `FORBIDDEN`, `502` is `INTERNAL`) and the body's `message` when it has one. |
| No response (offline, DNS, CORS) | `NETWORK`. |
| A missing path parameter | `BAD_REQUEST`, `Missing param "id" for orders.show`, before any request is sent. |

## Send auth tokens from the client

Give the client a token source and every request carries it:

```ts
// app/api/client.ts
import { createApiClient, registerRoutes } from 'kitr/api/client'
import type { AppRoutes } from '#server/routes'
import { app } from '#app/app'
import { routeTable } from './routes.gen'

export const api = createApiClient<AppRoutes>({
  baseUrl: 'https://app.acme.com',
  getToken: () => app.container.use('auth').getToken(),
  headers: () => ({ 'x-acme-team': 'team_7' }),
})
registerRoutes(api, [...routeTable])
```

`getToken` here comes from [Auth](/packages/auth). For cookie sessions, pass `credentials: 'include'` instead. On the server, `authMiddleware` from `kitr/auth/server` reads the token and sets `ctx.locals.user`.

## Call routes in-process

On the server, or in tests, pass the server's `fetch` so calls skip the network:

```ts
// server/jobs/nightly_report.ts
import { createApiClient, registerRoutes } from 'kitr/api/client'
import { server } from '#server/main'
import { type AppRoutes, routes } from '#server/routes'

const api = createApiClient<AppRoutes>({ baseUrl: 'http://internal', fetch: (request) => server.fetch(request) })
registerRoutes(api, routes.toJSON())

export async function nightlyReport() {
  const orders = await api.orders.index()
  return { count: orders.length }
}
```

## Mount routes on a server

`mountRoutes(server, routes)` turns the router into an h3 app and mounts it at `/`. `server/main.ts` does this for you:

```ts
// server/main.ts
import { createServer } from 'kitr/server'
import { mountRoutes } from 'kitr/api'
import { config } from '../config'
import rc from '../kitrrc'
import { routes } from './routes'

export const server = createServer({ providers: rc.providers, config })
mountRoutes(server, routes)
```

Pass a third argument to mount under a base path: `mountRoutes(server, partnerRoutes, '/partners')`. To serve the router from an h3 app you build yourself, call `toH3(routes, app)` with a kitr app; it returns the h3 app.

## Build URLs for named routes

`routes.url()` builds a path from a route name, with encoded parameters and an optional query string:

```ts
// server/mail/order_link.ts
import { routes } from '#server/routes'

routes.url('orders.show', { id: 'ord_1042' }, { expand: 'customer' })
// => '/api/orders/ord_1042?expand=customer'
```

An unknown name throws `[kitr/api] No route named "..."`, and a missing parameter throws `[kitr/api] Missing param "id" for route "orders.show"`.

## Generate an OpenAPI document

```sh
kitr api:sync
```

`kitr api:sync` loads `server/routes.ts` and writes two files:

- `openapi.json` (or `openapi.path` from `config/api.ts`): an OpenAPI 3.1 document. Every route becomes an operation with its name as `operationId`, path parameters, query parameters and request body from the validators, and the `KitrError` schema for `422`.
- `app/api/routes.gen.ts` (or `server/routes.gen.ts` when there is no `app/api/` folder): the route table for `registerRoutes`.

It prints `5 routes → openapi.json, app/api/routes.gen.ts`. Zod 4 schemas convert to JSON Schema automatically; valibot needs `@valibot/to-json-schema` installed; arktype converts itself. Schemas that can't be converted are left out.

Describe operations with `meta`:

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'
import OrdersController from '#server/controllers/orders_controller'

export const routes = defineRoutes((router) =>
  router.post('/api/orders/:id/refund', [OrdersController, 'refund'], {
    name: 'orders.refund',
    meta: { summary: 'Refund an order', tags: ['billing'], description: 'Refunds the full total to the card on file.' },
  }),
)

export type AppRoutes = typeof routes.$types
```

Build the document in code with `toOpenApi()`, for example to serve it from a route:

```ts
// server/main.ts
import { toOpenApi } from 'kitr/api'
// ...
server.h3.get('/openapi.json', () =>
  toOpenApi(routes, {
    title: 'Acme API',
    version: '1.0.0',
    servers: [{ url: 'https://app.acme.com' }],
  }),
)
```

| `toOpenApi` option | Default | Description |
| --- | --- | --- |
| `title` | `'kitr API'` | `info.title`. |
| `version` | `'0.0.0'` | `info.version`. |
| `description` | none | `info.description`. |
| `servers` | none | The `servers` list. |
| `schemaToJson` | zod, valibot, arktype | Function from a Standard Schema to JSON Schema, for other libraries. |

Operations without `meta.tags` are tagged with the first part of the route name (`orders`). Every operation documents a `200` response, including those that answer `201`.

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:controller <name>` | Writes `server/controllers/<name>_controller.ts` with one `handle` method. |
| `kitr make:controller <name> --resource` | Writes the controller with `index`, `show`, `store`, `update`, `destroy` and zod validators. |
| `kitr make:middleware <name>` | Writes `app/middleware/<name>.ts` with `defineMiddleware`. |
| `kitr api:sync` | Writes the OpenAPI document and the client route table. `--file` picks the routes file, `--out` the document path. |
| `kitr routes:list` | Prints every route: method, path and name. `--file` picks the routes file. |

`kitr make:controller orders --resource` writes:

```ts
// server/controllers/orders_controller.ts
import type { HttpContext } from 'kitr/api'
import { KitrError } from 'kitr/app'
import { z } from 'zod'

const createOrders = z.object({ name: z.string().min(2) })
const updateOrders = createOrders.partial()

export default class OrdersController {
  static validation = {
    store: { body: createOrders },
    update: { body: updateOrders },
  }

  async index({ query }: HttpContext) {
    return { items: [], page: Number(query.page ?? 1) }
  }

  async show({ params }: HttpContext<{ id: string }>) {
    throw KitrError.notFound('Orders ' + params.id)
  }

  async store({ body, response }: HttpContext<{}, {}, z.infer<typeof createOrders>>) {
    response.status(201)
    return { id: '1', ...body }
  }

  async update({ params, body }: HttpContext<{ id: string }, {}, z.infer<typeof updateOrders>>) {
    return { id: params.id, ...body }
  }

  async destroy({ params }: HttpContext<{ id: string }>) {
    void params
  }
}
```

`kitr make:middleware audit` writes:

```ts
// app/middleware/audit.ts
import { defineMiddleware } from 'kitr/api'

export const audit = defineMiddleware(async (ctx, next) => {
  // Before the handler
  const result = await next()
  // After the handler
  return result
})
```

`kitr routes:list` prints:

```text
  GET     /api/health                              health
  GET     /api/orders                              orders.index
  POST    /api/orders                              orders.store
  GET     /api/orders/:id                          orders.show
```

All three loaders look for `server/routes.ts`, then `app/api/routes.ts`, then `start/routes.ts`. Put a `stubs/controller.ts` in your project to change what `make:controller` writes.

## Errors

Every error reaches the client as JSON in this shape, and the typed client turns it back into a `KitrError`.

| Code | When | What to do |
| --- | --- | --- |
| `VALIDATION` (422) | A `params`, `query` or `body` schema failed, or `ctx.validate()` failed. `fieldErrors` lists every problem. | Show `fieldErrors` on the form; [Forms](/packages/forms) does it for you. |
| `BAD_REQUEST` (400) | The body is malformed JSON, `requireJson()` saw another content type, or the client was missing a path parameter. | Send valid JSON with `content-type: application/json`. |
| `UNAUTHORIZED` (401) | `authMiddleware` found no valid token, or a handler threw it. | Sign in, or send the token with `getToken`. |
| `FORBIDDEN` (403) | A permission check failed. | Check the user's abilities. |
| `NOT_FOUND` (404) | No route matches, a controller method is missing, or a handler threw it. | Check the path with `kitr routes:list`. |
| `CONFLICT` (409) | A handler threw it, such as for a duplicate. | Show the message; it is meant for the user. |
| `RATE_LIMITED` (429) | `rateLimit()` saw too many requests. | Wait for `ratelimit-reset` seconds. |
| `INTERNAL` (500) | A handler threw something that is not a `KitrError`, or the client called an unregistered route name. | Read the server log line with the request id; run `kitr api:sync`. |
| `NETWORK` (0) | The client got no response. | Check the connection and CORS. |

## Testing

Test routes through the server with `createTestClient` from [Testing](/packages/testing), or with the typed client pointed at `server.fetch`. No port is opened:

```ts
// test/orders.test.ts
import { createApiClient, registerRoutes } from 'kitr/api/client'
import { createTestClient } from 'kitr/testing'
import { describe, expect, it } from 'vitest'
import { server } from '#server/main'
import { type AppRoutes, routes } from '#server/routes'

const api = createApiClient<AppRoutes>({ baseUrl: 'http://test', fetch: (request) => server.fetch(request) })
registerRoutes(api, routes.toJSON())

describe('orders API', () => {
  it('lists and shows orders', async () => {
    const orders = await api.orders.index()
    expect(orders.map((order) => order.customer)).toContain('Ada')
    const order = await api.orders.show({ params: { id: 'ord_1042' } })
    expect(order).toMatchObject({ customer: 'Ada', total: 129 })
  })

  it('creates an order with 201', async () => {
    const res = await createTestClient(server).post('/api/orders', { customer: 'Grace', total: 480 })
    expect(res.status).toBe(201)
    expect(res.body).toMatchObject({ customer: 'Grace', total: 480, status: 'open' })
  })

  it('rejects an invalid order with field errors', async () => {
    await expect(api.orders.store({ body: { customer: 'A', total: -1 } })).rejects.toMatchObject({
      code: 'VALIDATION',
      status: 422,
      fieldErrors: { customer: expect.any(Array), total: expect.any(Array) },
    })
  })

  it('answers 404 for an unknown order', async () => {
    await expect(api.orders.show({ params: { id: 'ord_9999' } })).rejects.toMatchObject({
      code: 'NOT_FOUND',
      message: 'Order not found',
    })
  })
})
```

To test client code without a server, pass a fake `fetch` and assert on the requests it receives:

```ts
// test/order_client.test.ts
import { createApiClient, registerRoutes } from 'kitr/api/client'
import { expect, it, vi } from 'vitest'
import type { AppRoutes } from '#server/routes'

it('sends the token and the JSON body', async () => {
  const fetch = vi.fn(async (_request: Request) => Response.json({ id: 'ord_1043' }, { status: 201 }))
  const api = createApiClient<AppRoutes>({ baseUrl: 'https://app.acme.com', fetch, getToken: () => 'tok_ada' })
  registerRoutes(api, [{ name: 'orders.store', method: 'POST', path: '/api/orders' }])

  await api.orders.store({ body: { customer: 'Ada', total: 129 } })

  const request = fetch.mock.calls[0]![0]
  expect(request.url).toBe('https://app.acme.com/api/orders')
  expect(request.headers.get('authorization')).toBe('Bearer tok_ada')
  expect(await request.json()).toEqual({ customer: 'Ada', total: 129 })
})
```

To test one middleware, call it with a minimal context and a `next` function. Each test file gets a fresh module, so in-memory `rateLimit()` counters start at zero.

## Next steps

- [API reference](/packages/api/api)
- [Server](/packages/server): ports, request context, errors and shutdown
- [Auth](/packages/auth): `authMiddleware` and permissions for these routes
- [Query](/packages/query): the contracts the client produces
- [Forms](/packages/forms): showing `fieldErrors` on fields
- [A backend without React](/docs/pure-backend)


# Auth API

Source: https://kitr.dev/packages/auth/api

## Configuration

```ts
// config/auth.ts
defineConfig({
  adapter: AuthAdapter<TUser, TCredentials>, // required
  signInPath?: string,                       // where guards send anonymous users
  eager?: boolean,                           // load the session before first render; default true
})
```

The provider binds `auth` in the container and, unless `eager: false`, restores the session during boot.

## Session

```ts
interface Session<TUser> {
  user: TUser | null
  expiresAt?: number // epoch ms, when known
  can(ability: string, subject?: unknown): boolean
}
```

The router's `requireAuth()` and `can()` guards read `context.session`, which the provider supplies.

## Hooks

| Hook | Returns |
| --- | --- |
| `useAuth()` | The `Auth` object: `session`, `user`, `load()`, `signIn(credentials)`, `signOut()`, `refresh()`, `getToken()`, `subscribe(listener)`. |
| `useSession()` | The live `Session`. Re-renders on sign-in and sign-out. |
| `useUser()` | `session.user`. |
| `useCan()` | `session.can`. |

## Adapters

### tokenAdapter

```ts
tokenAdapter<TUser, TCredentials = { email: string; password: string }>({
  fetchUser: (token) => Promise<TUser | null>,                       // required
  signIn?: (credentials) => Promise<{ token; refreshToken?; user? }>,
  refresh?: (refreshToken) => Promise<{ token; refreshToken? } | null>,
  signOut?: (token) => Promise<void>,
  storage?: TokenStorage,        // default memoryStorage()
  refreshStorage?: TokenStorage, // default memoryStorage()
  abilities?: Abilities<TUser>,
})
```

`memoryStorage()` and `localStorageTokens(key = 'kitr:token')` are the built-in `TokenStorage`s. Write your own with `{ get(), set(token) }`.

### betterAuthAdapter

```ts
betterAuthAdapter<TUser>(client, { abilities?, signIn?: (client, credentials) => Promise<unknown> })
```

Uses `client.signIn.email` unless you pass `signIn`.

### customAdapter

```ts
customAdapter<TUser, TCredentials>({
  getSession: () => Promise<Session<TUser> | null>, // required
  signIn?, signOut?, refresh?, getToken?, onChange?,
})
```

Build sessions with `createSession(user, abilities?, { expiresAt? })`.

## defineAbilities

```ts
const abilities = defineAbilities<User>({ 'name': (user, subject?) => boolean })

abilities.can(user, 'name', subject) // false when user is null
abilities.for(user)('name', subject)
```

Checks return `false` for an anonymous user, an unknown ability and a rule that throws. Annotate `user` in each rule instead of passing `<User>` to keep the ability names typed.

## kitr/auth/server

No React. Works with any `@kitr/api` router.

```ts
authMiddleware<TUser>({
  verify: (token, ctx) => TUser | null | Promise<TUser | null>, // required
  from?: 'bearer' | { cookie: string }, // default 'bearer'
  optional?: boolean,                   // let anonymous requests through
  abilities?: Abilities<TUser>,
})

requireUser<TUser>(ctx): TUser        // throws 401 when anonymous
currentUser<TUser>(ctx): TUser | null
```

The middleware sets `ctx.locals.user` and `ctx.locals.can(ability, subject)`, and throws `401 UNAUTHORIZED` when there is no valid user and `optional` is off.


# Auth

Source: https://kitr.dev/packages/auth

Almost every screen in an app asks two questions: who is this, and are they allowed to do that? `kitr/auth` answers both, in the browser and on the server, with the same rules in both places. It gives the app one session to read, guards for pages, and permission checks written once as plain functions.

It doesn't store passwords or run a login server. It connects to what you already have, such as your own API's token endpoint or [Better Auth](https://www.better-auth.com/docs), through an adapter. On top it adds React hooks, router guards for [Router](/packages/router), and middleware for [API routes](/packages/api).

The session, hooks and adapters run in the browser. `kitr/auth/server` runs on the server and has no React dependency. If all you need is to protect API routes with a token your server checks, use `kitr/auth/server` alone.

The examples on this page follow Acme's project tracker at `app.acme.com`. Ada is an admin, Grace and Linus are members, and members can edit only the projects they own.

## Install

```sh
kitr add auth
```

What `kitr add auth` does:

- Installs `@kitr/auth` and adds it to `packages` in `kitrrc.ts`.
- Registers `() => import('@kitr/auth/provider')` in `providers` in `kitrrc.ts`.
- Writes `app/abilities.ts`, with a `User` type and one permission rule.
- Writes `config/auth.ts` (shown under Configure) and adds it to `config/index.ts`.
- Adds a `kitr: auth` section to `AGENTS.md`.

The generated permissions file:

```ts
// app/abilities.ts
import { defineAbilities } from 'kitr/auth'

export interface User {
  id: string
  email: string
  role: 'admin' | 'member'
}

export const abilities = defineAbilities({
  'projects.update': (user: User, project: { ownerId: string }) => user.role === 'admin' || project.ownerId === user.id,
})
```

`kitr/auth` is a client package: in a server-only project, `kitr add auth` skips it. Use `kitr/auth/server` from `@kitr/auth` there by installing the package yourself. The `app`, `fullstack`, `saas`, `desktop` and `mobile` kits include auth already.

`kitr remove auth` unregisters the provider, removes `@kitr/auth` from `package.json` and `kitrrc.ts`, deletes `config/auth.ts` and drops the `AGENTS.md` section. It keeps `app/abilities.ts` and lists the files that still import `kitr/auth`.

## Configure

`kitr add auth` writes this file:

```ts
// config/auth.ts
import { defineConfig, localStorageTokens, tokenAdapter } from 'kitr/auth'
import { type User, abilities } from '#app/abilities'
import { env } from '#app/env'

// Swap for betterAuthAdapter(createAuthClient()) or a customAdapter({...}).
const adapter = tokenAdapter<User>({
  abilities,
  storage: localStorageTokens(),
  fetchUser: async (token) => {
    const res = await fetch(`${env.VITE_API_URL}/me`, { headers: { authorization: `Bearer ${token}` } })
    return res.ok ? ((await res.json()) as User) : null
  },
  signIn: async (credentials) => {
    const res = await fetch(`${env.VITE_API_URL}/sign-in`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(credentials) })
    if (!res.ok) throw new Error('Invalid credentials')
    return (await res.json()) as { token: string; refreshToken?: string }
  },
})

export default defineConfig({ adapter, signInPath: '/sign-in' })
```

| Option | Default | Description |
| --- | --- | --- |
| `adapter` | required | Where sessions come from: `tokenAdapter`, `betterAuthAdapter` or `customAdapter`. See "Adapters". |
| `signInPath` | `'/sign-in'` | Documents your sign-in page. The router guard does not read it; pass the path to `requireAuth({ to })` when it differs from `/sign-in`. |
| `eager` | `true` | Restore the session while the app boots, before the first render. `false` waits until you call `auth.load()`. |

| Variable | Used for |
| --- | --- |
| `VITE_API_URL` | The API that answers `/me` and `/sign-in` in the generated config. |

`kitr add auth` does not declare `VITE_API_URL`. The [HTTP](/packages/http) recipe does, and the `app` kit includes it. Without HTTP, add it to `app/env.ts` yourself:

```ts
// app/env.ts
import { createEnv, env as e } from 'kitr/env'

export const env = createEnv({
  public: {
    VITE_APP_NAME: e.string({ default: 'acme' }),
    VITE_API_URL: e.url({ default: 'https://app.acme.com/api' }),
  },
  server: {},
})
```

## Show who is signed in

With the provider registered, every component can read the session. Show Ada her name and a sign-out button:

```tsx
// app/components/account_menu.tsx
import { useAuth, useUser } from 'kitr/auth'
import { Link } from 'kitr/router'
import type { User } from '#app/abilities'

export function AccountMenu() {
  const auth = useAuth()
  const user = useUser<User>()
  if (!user) return <Link to="/sign-in">Sign in</Link>
  return (
    <button type="button" onClick={() => auth.signOut()}>
      Sign out {user.email}
    </button>
  )
}
```

Render `<AccountMenu />` in your layout. Before sign-in it shows "Sign in"; after Ada signs in it shows "Sign out ada@acme.com". The component re-renders on every sign-in and sign-out, in any part of the app.

| Hook | Returns |
| --- | --- |
| `useAuth()` | The `auth` service: `signIn`, `signOut`, `refresh`, `load`, `getToken`, `session`, `user`. |
| `useSession()` | The current session: `{ user, expiresAt, can }`. |
| `useUser()` | The signed-in user, or `null`. |
| `useCan()` | The session's `can(ability, subject)` function. |

## Sign users in

Call `auth.signIn(credentials)` with whatever your adapter expects. It resolves with the new session and throws when the credentials are wrong:

```tsx
// app/routes/sign-in.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useAuth } from 'kitr/auth'
import { useNavigate } from 'kitr/router'
import { type FormEvent, useState } from 'react'
import type { User } from '#app/abilities'

export const Route = createFileRoute('/sign-in')({
  validateSearch: (search: Record<string, unknown>) => ({
    redirect: typeof search.redirect === 'string' ? search.redirect : undefined,
  }),
  component: SignInPage,
})

function SignInPage() {
  const { redirect } = Route.useSearch()
  const navigate = useNavigate()
  const auth = useAuth<User, { email: string; password: string }>()
  const [error, setError] = useState<string | null>(null)

  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    const data = new FormData(event.currentTarget)
    try {
      await auth.signIn({ email: String(data.get('email')), password: String(data.get('password')) })
      await navigate({ to: redirect ?? '/' })
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Sign-in failed')
    }
  }

  return (
    <form onSubmit={onSubmit}>
      {error && <p role="alert">{error}</p>}
      <input name="email" type="email" autoComplete="email" placeholder="ada@acme.com" />
      <input name="password" type="password" autoComplete="current-password" />
      <button type="submit">Sign in</button>
    </form>
  )
}
```

`redirect` is the page the visitor tried to open before the guard sent them here. With the generated config, wrong credentials throw `Invalid credentials`. With [Forms](/packages/forms), pass `auth.signIn` to the form's `onSubmit` and the error shows at the top of the form.

## Sign users out

```tsx
// app/components/sign_out_button.tsx
import { useAuth } from 'kitr/auth'
import { useNavigate } from 'kitr/router'

export function SignOutButton() {
  const auth = useAuth()
  const navigate = useNavigate()
  return (
    <button
      type="button"
      onClick={async () => {
        await auth.signOut()
        await navigate({ to: '/sign-in' })
      }}
    >
      Sign out
    </button>
  )
}
```

`signOut()` calls the adapter's `signOut` (for tokens, your API's sign-out endpoint when you configure one), clears stored tokens and sets the session to anonymous. `tokenAdapter` ignores a failing sign-out endpoint, so the user is always signed out locally. With `customAdapter` and `betterAuthAdapter`, an error from the adapter's `signOut` rejects and leaves the session as it was.

## Adapters

An adapter turns your backend into a session. Every adapter produces the same `Session`, so hooks, guards and permissions work the same with any of them.

### Your own API with tokens

`tokenAdapter` works with any backend that issues bearer tokens: an Acme API built with [API routes](/packages/api), a JWT service, or another framework. It needs `fetchUser`; `signIn`, `refresh` and `signOut` are optional:

```ts
// config/auth.ts
import { defineConfig, localStorageTokens, tokenAdapter } from 'kitr/auth'
import { type User, abilities } from '#app/abilities'
import { env } from '#app/env'

const adapter = tokenAdapter<User>({
  abilities,
  storage: localStorageTokens(),
  fetchUser: async (token) => {
    const res = await fetch(`${env.VITE_API_URL}/me`, { headers: { authorization: `Bearer ${token}` } })
    return res.ok ? ((await res.json()) as User) : null
  },
  signIn: async (credentials) => {
    const res = await fetch(`${env.VITE_API_URL}/sign-in`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(credentials),
    })
    if (!res.ok) throw new Error('Wrong email or password')
    return (await res.json()) as { token: string; refreshToken?: string; user?: User }
  },
  signOut: async (token) => {
    await fetch(`${env.VITE_API_URL}/sign-out`, { method: 'POST', headers: { authorization: `Bearer ${token}` } })
  },
})

export default defineConfig({ adapter })
```

| Option | Default | Description |
| --- | --- | --- |
| `fetchUser` | required | `(token) => user or null`. Called on boot and after sign-in. Return `null` for an invalid token. |
| `signIn` | none | `(credentials) => { token, refreshToken?, user? }`. When it returns `user`, `fetchUser` is skipped. |
| `refresh` | none | `(refreshToken) => { token, refreshToken? } or null`. See "Refresh expired tokens". |
| `signOut` | none | `(token) => void`. Tells your API to revoke the token. |
| `storage` | memory | Where the access token lives. See "Keep users signed in across reloads". |
| `refreshStorage` | memory | Where the refresh token lives. |
| `abilities` | none | Your `defineAbilities` result, for `session.can`. Without it, `can()` is true for any signed-in user. |

The second type parameter types the credentials: `tokenAdapter<User, { email: string; code: string }>` for a one-time-code sign-in. The default is `{ email: string; password: string }`.

### Better Auth

`betterAuthAdapter` wraps a [Better Auth client](https://www.better-auth.com/docs/concepts/client). The session lives in Better Auth's cookie, so nothing is stored in the browser:

```sh
pnpm add better-auth
```

```ts
// config/auth.ts
import { createAuthClient } from 'better-auth/react'
import { betterAuthAdapter, defineConfig } from 'kitr/auth'
import { type User, abilities } from '#app/abilities'

const client = createAuthClient({ baseURL: 'https://app.acme.com' })

export default defineConfig({
  adapter: betterAuthAdapter<User>(client, { abilities }),
})
```

`signIn({ email, password })` calls `client.signIn.email()` and then reads the session. Pass your own `signIn` to use another method, such as a social provider:

```ts
// config/auth.ts
import { createAuthClient } from 'better-auth/react'
import { betterAuthAdapter, defineConfig } from 'kitr/auth'
import { type User, abilities } from '#app/abilities'

const client = createAuthClient({ baseURL: 'https://app.acme.com' })

export default defineConfig({
  adapter: betterAuthAdapter<User, { provider: 'github' | 'google' }>(client, {
    abilities,
    signIn: (c, { provider }) => c.signIn!.social({ provider }),
  }),
})
```

The session's `expiresAt` comes from Better Auth's session. Better Auth runs its own server; see [its installation guide](https://www.better-auth.com/docs/installation).

### Any other backend

`customAdapter` takes the functions you have. Only `getSession` is required. Build the session with `createSession(user, abilities)`:

```ts
// config/auth.ts
import { createSession, customAdapter, defineConfig } from 'kitr/auth'
import { type User, abilities } from '#app/abilities'

const adapter = customAdapter<User, { email: string; password: string }>({
  async getSession() {
    const res = await fetch('https://app.acme.com/api/session', { credentials: 'include' })
    if (!res.ok) return null
    return createSession((await res.json()) as User, abilities)
  },
  async signIn(credentials) {
    const res = await fetch('https://app.acme.com/api/session', {
      method: 'POST',
      credentials: 'include',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(credentials),
    })
    if (!res.ok) throw new Error('Wrong email or password')
    return createSession((await res.json()) as User, abilities)
  },
  async signOut() {
    await fetch('https://app.acme.com/api/session', { method: 'DELETE', credentials: 'include' })
  },
})

export default defineConfig({ adapter })
```

For a reusable adapter, such as one for Firebase or Clerk, see "Extend".

## Keep users signed in across reloads

`tokenAdapter` keeps tokens in memory by default. That is the safest place, but the user is signed out when the page reloads. `localStorageTokens()` keeps the access token across reloads, under the key `kitr:token`:

```ts
// config/auth.ts
import { defineConfig, localStorageTokens, memoryStorage, tokenAdapter } from 'kitr/auth'
import { type User, abilities } from '#app/abilities'
import { env } from '#app/env'

const adapter = tokenAdapter<User>({
  abilities,
  storage: localStorageTokens('acme:token'),
  refreshStorage: memoryStorage(),
  fetchUser: async (token) => {
    const res = await fetch(`${env.VITE_API_URL}/me`, { headers: { authorization: `Bearer ${token}` } })
    return res.ok ? ((await res.json()) as User) : null
  },
})

export default defineConfig({ adapter })
```

> **Warning**
> Any script on your page can read `localStorage`, so an XSS bug exposes the token. Keep access tokens short-lived, keep refresh tokens in memory, or use a cookie session (Better Auth or `customAdapter`) for sensitive apps.

Storage that throws, such as in a private window, is ignored: reads return `null`. To store tokens elsewhere, such as [Secure storage](/packages/secure-storage) in a mobile app, pass any object with `get()` and `set(token)`:

```ts
// app/auth/secure_tokens.ts
import type { TokenStorage } from 'kitr/auth'
import { app } from '#app/app'

export const secureTokens: TokenStorage = {
  get: () => app.container.use('secureStorage').get('acme.token'),
  set: (token) =>
    token === null
      ? app.container.use('secureStorage').remove('acme.token')
      : app.container.use('secureStorage').set('acme.token', token),
}
```

Both methods may return a promise.

## Refresh expired tokens

Give `tokenAdapter` a `refresh` function, and `auth.refresh()` swaps the stored refresh token for a new access token:

```ts
// config/auth.ts
import { defineConfig, localStorageTokens, tokenAdapter } from 'kitr/auth'
import { type User, abilities } from '#app/abilities'
import { env } from '#app/env'

const adapter = tokenAdapter<User>({
  abilities,
  storage: localStorageTokens(),
  fetchUser: async (token) => {
    const res = await fetch(`${env.VITE_API_URL}/me`, { headers: { authorization: `Bearer ${token}` } })
    return res.ok ? ((await res.json()) as User) : null
  },
  signIn: async (credentials) => {
    const res = await fetch(`${env.VITE_API_URL}/sign-in`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(credentials),
    })
    if (!res.ok) throw new Error('Wrong email or password')
    return (await res.json()) as { token: string; refreshToken: string }
  },
  refresh: async (refreshToken) => {
    const res = await fetch(`${env.VITE_API_URL}/refresh`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ refreshToken }),
    })
    return res.ok ? ((await res.json()) as { token: string; refreshToken?: string }) : null
  },
})

export default defineConfig({ adapter })
```

`auth.refresh()` resolves `true` when a new token was stored. It resolves `false`, and signs the user out, when there is no refresh token, when `refresh` returns `null` or throws, or when the adapter has no `refresh` at all. Don't call `refresh()` to check whether a user is signed in; read `auth.user`.

You rarely call it yourself. Point the HTTP client at it, and a `401` triggers one refresh and a retry (next section).

## Send the token with every request

[HTTP](/packages/http) takes the token and the refresh function from the `auth` service:

```ts
// config/http.ts
import { defineConfig } from 'kitr/http'
import { app } from '#app/app'
import { env } from '#app/env'

export default defineConfig({
  baseUrl: env.VITE_API_URL,
  getToken: () => app.container.use('auth').getToken(),
  refresh: () => app.container.use('auth').refresh(),
})
```

Every request sends `Authorization: Bearer <token>`. On a `401`, the client calls `refresh()` once and retries; when refresh fails, the user is signed out and the request rejects with `UNAUTHORIZED`. The typed [API client](/packages/api) takes the same `getToken` option.

`auth.getToken()` resolves `null` for adapters without tokens, such as Better Auth, whose cookie the browser sends for you.

## Protect pages

Pages are guarded in `beforeLoad` with `requireAuth()` from [Router](/packages/router). It reads `session` from the router context and redirects anonymous visitors.

First, put the live session in the router context:

```tsx
// app/router.tsx
import type { Session } from 'kitr/auth'
import { createKitrRouter } from 'kitr/router'
import type { User } from '#app/abilities'
import { app } from './app'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  return createKitrRouter({
    routeTree,
    app,
    context: {
      // A live getter, so `requireAuth()` sees the session the auth provider restores during boot.
      get session() {
        return app.container.has('auth') ? (app.container.use('auth').session as Session<User>) : null
      },
    },
  })
}

declare module '@tanstack/react-router' {
  interface Register {
    router: ReturnType<typeof getRouter>
  }
}

declare module '@kitr/router' {
  interface KitrRouterContext {
    session: Session<User> | null
  }
}
```

Then guard a layout route. Every page under `_app` needs a signed-in user:

```tsx
// app/routes/_app.tsx
import { createFileRoute, Outlet } from '@tanstack/react-router'
import { requireAuth } from 'kitr/router'

export const Route = createFileRoute('/_app')({
  beforeLoad: requireAuth(),
  component: () => <Outlet />,
})
```

An anonymous visitor to `/projects` goes to `/sign-in`, with the `redirect` search parameter set to `/projects`. The sign-in page above sends them back after they sign in. `requireAuth({ to: '/login', redirectParam: 'next' })` changes the path and the parameter name; `redirectParam: false` leaves the parameter off.

The router may copy its context object when it is created, which reads the getter once. When the session changes after the router exists, read it from the container in the guard so it is always current:

```tsx
// app/routes/_app.tsx
import { createFileRoute, Outlet } from '@tanstack/react-router'
import type { Session } from 'kitr/auth'
import { requireAuth } from 'kitr/router'
import type { User } from '#app/abilities'

export const Route = createFileRoute('/_app')({
  beforeLoad: async ({ context, location }) => {
    await context.app.boot()
    const session = context.app.container.use('auth').session as Session<User>
    return requireAuth()({ context: { session }, location })
  },
  component: () => <Outlet />,
})
```

The `saas` kit uses this form. With tokens in `localStorage` the server can't see the session, so run guarded routes on the client only, for example with `ssrRoute(false)` from [SEO](/packages/seo).

## Define permissions

Write each rule once, as a function of the user and an optional subject, in `app/abilities.ts`:

```ts
// app/abilities.ts
import { defineAbilities } from 'kitr/auth'

export interface User {
  id: string
  email: string
  role: 'admin' | 'member'
  teamId: string
}

export interface Project {
  id: string
  ownerId: string
  teamId: string
}

export const abilities = defineAbilities({
  'projects.update': (user: User, project: Project) => user.role === 'admin' || project.ownerId === user.id,
  'projects.view': (user: User, project: Project) => project.teamId === user.teamId,
  'invoices.view': (user: User) => user.role === 'admin',
  'teams.invite': (user: User) => user.role === 'admin',
})
```

Annotate `user` in each rule and leave off the type argument. TypeScript then knows the ability names, so `abilities.can(user, 'projects.updte')` fails to compile. `defineAbilities<User>({...})` also works, but the names widen to `string`.

Check a rule anywhere, on the client or the server:

```ts
// app/features/projects/permissions.ts
import { abilities, type Project, type User } from '#app/abilities'

const ada: User = { id: 'u_ada', email: 'ada@acme.com', role: 'admin', teamId: 't_core' }
const grace: User = { id: 'u_grace', email: 'grace@acme.com', role: 'member', teamId: 't_core' }
const roadmap: Project = { id: 'p_roadmap', ownerId: 'u_ada', teamId: 't_core' }

abilities.can(ada, 'projects.update', roadmap)
// => true
abilities.can(grace, 'projects.update', roadmap)
// => false
abilities.can(null, 'projects.view', roadmap)
// => false

const graceCan = abilities.for(grace)
graceCan('projects.view', roadmap)
// => true
```

Three rules hold for every check: an anonymous user (`null` or `undefined`) never passes, an ability that doesn't exist returns `false`, and a rule that throws returns `false`.

## Check permissions in components

`useCan()` returns the session's `can`, bound to the signed-in user. Use it to hide what the user can't do:

```tsx
// app/features/projects/project_header.tsx
import { useCan } from 'kitr/auth'
import type { Project } from '#app/abilities'

export function ProjectHeader({ project }: { project: Project }) {
  const can = useCan()
  return (
    <header>
      <h1>Roadmap</h1>
      {can('projects.update', project) && <button type="button">Edit project</button>}
      {can('teams.invite') && <button type="button">Invite to team</button>}
    </header>
  )
}
```

Grace sees "Edit project" on her own projects only; Ada sees both buttons everywhere. Hiding a button is not security: check the same ability on the server too (see "Protect API routes").

## Check permissions on routes

`can()` from [Router](/packages/router) blocks a page for users without an ability. It reads `context.session` like `requireAuth()`:

```tsx
// app/routes/_app/invoices.tsx
import { createFileRoute } from '@tanstack/react-router'
import { can } from 'kitr/router'

export const Route = createFileRoute('/_app/invoices')({
  beforeLoad: can('invoices.view'),
  component: () => <h1>Invoices</h1>,
})
```

Grace gets the route's error screen with a `FORBIDDEN` error, `Missing permission "invoices.view"`. Pass `{ to: '/' }` to redirect instead, or `{ subject }` to check against one record. Don't confuse it with `can` from `kitr/auth/server`, which is API middleware.

## Use the session outside components

The provider binds the `auth` service in the container. Use it in loaders, stores and services:

```ts
// app/features/projects/loaders.ts
import { app } from '#app/app'

const auth = app.container.use('auth')

auth.user
// => { id: 'u_ada', email: 'ada@acme.com', role: 'admin', teamId: 't_core' }
auth.session.can('invoices.view')
// => true

const stop = auth.subscribe((session) => {
  console.log(session.user ? `signed in as ${(session.user as { email: string }).email}` : 'signed out')
})
await auth.signOut()
// logs: signed out
stop()
```

| Member | Description |
| --- | --- |
| `session` | The current session; anonymous is `{ user: null, can: () => false }`. |
| `user` | `session.user`. |
| `load()` | Asks the adapter for the session again. Errors become an anonymous session. |
| `signIn(credentials)` | Signs in and resolves with the session. |
| `signOut()` | Signs out and clears the local session. |
| `refresh()` | Refreshes tokens; resolves `false` and signs out when it can't. |
| `getToken()` | The bearer token, or `null`. |
| `subscribe(listener)` | Calls `listener(session)` on every change, once per change. Returns an unsubscribe function. |
| `toContext()` | `{ session }` with a live getter, for router context. |
| `adapter` | The adapter from the config. |

With `eager: false`, the session stays anonymous until something calls `auth.load()`, such as a guard on the first protected route. Use it when the session check is slow and most pages are public.

## Protect API routes

On the server, `authMiddleware` from `kitr/auth/server` reads the token, finds the user and puts them on `ctx.locals`. It works with any [API routes](/packages/api) router:

```ts
// server/routes.ts
import { cors, defineRoutes } from 'kitr/api'
import { authMiddleware } from 'kitr/auth/server'
import { abilities, type User } from '#app/abilities'
import ProjectsController from '#server/controllers/projects_controller'
import { findUserByToken } from '#server/services/sessions'

const auth = authMiddleware<User>({ verify: (token) => findUserByToken(token), abilities })

export const routes = defineRoutes((router) =>
  router.group({ prefix: '/api', middleware: [cors(), auth] }, (api) =>
    api.resource('projects', ProjectsController),
  ),
)

export type AppRoutes = typeof routes.$types
```

A request without a token, or with one `verify` rejects, answers `401`:

```json
{ "code": "UNAUTHORIZED", "message": "Authentication required", "status": 401 }
```

| Option | Default | Description |
| --- | --- | --- |
| `verify` | required | `(token, ctx) => user or null`. Look the token up, or verify a JWT. May be async. |
| `from` | `'bearer'` | `'bearer'` reads `Authorization: Bearer <token>`; `{ cookie: 'name' }` reads a cookie. |
| `optional` | `false` | Let anonymous requests through with `ctx.locals.user = null`. |
| `abilities` | none | Your abilities, for `ctx.locals.can`. Without it, `can()` is true for any signed-in user. |

Import the same `abilities` from `app/abilities.ts` on both sides, so the browser and the API agree on every rule.

## Read the user in a controller

`requireUser(ctx)` returns the user `authMiddleware` set, typed, or throws `401`. `currentUser(ctx)` returns `null` instead, for routes with `optional: true`:

```ts
// server/controllers/projects_controller.ts
import type { HttpContext } from 'kitr/api'
import { KitrError } from 'kitr/app'
import { currentUser, requireUser } from 'kitr/auth/server'
import { abilities, type Project, type User } from '#app/abilities'

const projects = new Map<string, Project>([['p_roadmap', { id: 'p_roadmap', ownerId: 'u_ada', teamId: 't_core' }]])

export default class ProjectsController {
  async index(ctx: HttpContext) {
    const user = currentUser<User>(ctx)
    return [...projects.values()].filter((project) => abilities.can(user, 'projects.view', project))
  }

  async update(ctx: HttpContext<{ id: string }>) {
    const user = requireUser<User>(ctx)
    const project = projects.get(ctx.params.id)
    if (!project) throw KitrError.notFound('Project')
    if (!abilities.can(user, 'projects.update', project)) throw KitrError.forbidden()
    return { ...project, updatedBy: user.id }
  }
}
```

`authMiddleware` also sets `ctx.locals.can(ability, subject)`, bound to the request's user, for code that has the context but not the user.

## Require a permission on an API route

`can()` from `kitr/auth/server` is middleware. It loads the subject from the context, checks the ability, and answers `403` before the handler runs:

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'
import { authMiddleware, can } from 'kitr/auth/server'
import { abilities, type User } from '#app/abilities'
import InvoicesController from '#server/controllers/invoices_controller'
import ProjectsController from '#server/controllers/projects_controller'
import { findProject } from '#server/services/projects'
import { findUserByToken } from '#server/services/sessions'

const auth = authMiddleware<User>({ verify: (token) => findUserByToken(token), abilities })

export const routes = defineRoutes((router) =>
  router.group({ prefix: '/api', middleware: [auth] }, (api) =>
    api
      .get('/invoices', [InvoicesController, 'index'], {
        name: 'invoices.index',
        middleware: [can('invoices.view')],
      })
      .patch('/projects/:id', [ProjectsController, 'update'], {
        name: 'projects.update',
        middleware: [can('projects.update', (ctx) => findProject(ctx.params.id))],
      }),
  ),
)

export type AppRoutes = typeof routes.$types
```

Grace calling `GET /api/invoices` gets:

```json
{ "code": "FORBIDDEN", "message": "Missing permission \"invoices.view\"", "status": 403 }
```

Put `can()` after `authMiddleware`; on its own it finds no user and answers `403` for everyone.

## Read the session from a cookie

For cookie sessions, such as a cookie your sign-in endpoint sets, read the token from the cookie by name:

```ts
// server/middleware/auth.ts
import { authMiddleware } from 'kitr/auth/server'
import { abilities, type User } from '#app/abilities'
import { findUserBySession } from '#server/services/sessions'

export const auth = authMiddleware<User>({
  from: { cookie: 'acme_session' },
  verify: (sessionId) => findUserBySession(sessionId),
  abilities,
})

export const optionalAuth = authMiddleware<User>({
  from: { cookie: 'acme_session' },
  optional: true,
  verify: (sessionId) => findUserBySession(sessionId),
  abilities,
})
```

The cookie value is URL-decoded before `verify` sees it. A malformed value counts as no cookie, not as a server error. Use `optionalAuth` on public pages that show more to signed-in users, such as a project page with an edit link for its owner.

> **Warning**
> Cookie sessions need CSRF protection on writes, because the browser sends the cookie with requests other sites trigger. Turn on CSRF in [Shield](/packages/shield).

## Errors

| Code | When | What to do |
| --- | --- | --- |
| `UNAUTHORIZED` (401) | `authMiddleware` found no token or `verify` returned `null`; `requireUser()` found no user. Message: `Authentication required`. | Sign in, or send the token with `getToken`. |
| `FORBIDDEN` (403) | `can()` middleware or the router's `can()` guard failed. Message: `Missing permission "<ability>"`. | Check the user's role, or hide the action with `useCan()`. |
| `UNAUTHORIZED` (401) | `tokenAdapter`'s `signIn` returned a token, but neither it nor `fetchUser` returned a user. Message: `Sign-in succeeded but no user was returned`. Stored tokens are cleared. | Make `/me` accept the new token, or return `user` from `signIn`. |
| `UNAUTHORIZED` (401) | `betterAuthAdapter` signed in but Better Auth has no session. Message: `Sign-in failed`. | Check Better Auth's cookie settings and base URL. |
| `INTERNAL` (500) | `signIn()` on a `tokenAdapter` without `signIn` (`tokenAdapter: signIn not configured`), or a `betterAuthAdapter` with no email sign-in (`betterAuthAdapter: no signIn configured`). | Configure `signIn` on the adapter. |

`auth.signIn()` on a custom adapter without `signIn` throws a plain `Error`: `[kitr/auth] adapter has no signIn`. Errors your own `signIn` throws, such as `Invalid credentials` in the generated config, reach the caller unchanged. Throw `KitrError.unauthorized('Wrong email or password')` from `kitr/app` instead to get a kitr error with a `401` status.

## Testing

Test with a fake adapter: `customAdapter` with an in-memory user, booted with `createTestApp` from [Testing](/packages/testing). No network, no storage:

```tsx
// test/auth.test.tsx
import { act, screen } from '@testing-library/react'
import { createSession, customAdapter, useCan, useUser } from 'kitr/auth'
import authProvider from 'kitr/auth/provider'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { describe, expect, it } from 'vitest'
import { abilities, type User } from '#app/abilities'

const ada: User = { id: 'u_ada', email: 'ada@acme.com', role: 'admin', teamId: 't_core' }
const grace: User = { id: 'u_grace', email: 'grace@acme.com', role: 'member', teamId: 't_core' }

function fakeAdapter(start: User | null) {
  let current = start
  const people: Record<string, User> = { 'ada@acme.com': ada, 'grace@acme.com': grace }
  return customAdapter<User, { email: string }>({
    getSession: async () => (current ? createSession(current, abilities) : null),
    signIn: async ({ email }) => {
      current = people[email] ?? null
      if (!current) throw new Error('Wrong email or password')
      return createSession(current, abilities)
    },
    signOut: async () => {
      current = null
    },
  })
}

function InvoicesLink() {
  const user = useUser<User>()
  const can = useCan()
  if (!user) return <p>Signed out</p>
  return <p>{can('invoices.view') ? `${user.email} sees invoices` : `${user.email} has no invoices`}</p>
}

describe('auth', () => {
  it('restores the session on boot', async () => {
    const app = await createTestApp({ providers: [authProvider], config: { auth: { adapter: fakeAdapter(ada) } } })
    expect(app.container.use('auth').user).toEqual(ada)
  })

  it('follows sign-in and sign-out in components', async () => {
    const app = await createTestApp({ providers: [authProvider], config: { auth: { adapter: fakeAdapter(null) } } })
    renderWithKitr(<InvoicesLink />, { app })
    expect(screen.getByText('Signed out')).toBeTruthy()

    await act(() => app.container.use('auth').signIn({ email: 'grace@acme.com' }))
    expect(screen.getByText('grace@acme.com has no invoices')).toBeTruthy()

    await act(() => app.container.use('auth').signOut())
    await act(() => app.container.use('auth').signIn({ email: 'ada@acme.com' }))
    expect(screen.getByText('ada@acme.com sees invoices')).toBeTruthy()
  })

  it('rejects unknown people', async () => {
    const app = await createTestApp({ providers: [authProvider], config: { auth: { adapter: fakeAdapter(null) } } })
    await expect(app.container.use('auth').signIn({ email: 'linus@acme.com' })).rejects.toThrow('Wrong email or password')
    expect(app.container.use('auth').user).toBeNull()
  })
})
```

Test the server middleware by calling it with a minimal context. It needs only `request.header()` and `locals`:

```ts
// test/auth_middleware.test.ts
import { authMiddleware, can, requireUser } from 'kitr/auth/server'
import { describe, expect, it } from 'vitest'
import { abilities, type User } from '#app/abilities'

const grace: User = { id: 'u_grace', email: 'grace@acme.com', role: 'member', teamId: 't_core' }
const auth = authMiddleware<User>({ verify: (token) => (token === 'tok_grace' ? grace : null), abilities })

const ctx = (authorization: string | null) => ({
  request: { header: (name: string) => (name === 'authorization' ? authorization : null) },
  locals: {} as Record<string, unknown>,
})

describe('auth middleware', () => {
  it('rejects a request without a token', async () => {
    await expect(auth(ctx(null), async () => 'handler')).rejects.toMatchObject({ code: 'UNAUTHORIZED', status: 401 })
  })

  it('sets the user for a valid token', async () => {
    const request = ctx('Bearer tok_grace')
    expect(await auth(request, async () => 'handler')).toBe('handler')
    expect(requireUser<User>(request).email).toBe('grace@acme.com')
  })

  it('blocks members from invoices', async () => {
    const request = ctx('Bearer tok_grace')
    await auth(request, async () => null)
    await expect(can('invoices.view')(request, async () => 'handler')).rejects.toMatchObject({
      code: 'FORBIDDEN',
      message: 'Missing permission "invoices.view"',
    })
  })
})
```

For full request tests through the server, send `authorization: Bearer <token>` with `createTestClient(server, { headers })` from [Testing](/packages/testing).

## Extend

Write an adapter when your identity provider has its own client, such as Firebase, Clerk or a company SSO. An adapter implements the `AuthAdapter` interface; see [`AuthAdapter`](/packages/auth/api) in the API reference:

| Member | Required | Description |
| --- | --- | --- |
| `getSession()` | yes | Resolves the current session, or `null` when anonymous. Called on boot and by `auth.load()`. |
| `signIn(credentials)` | no | Signs in and resolves the new session. |
| `signOut()` | no | Ends the session at the provider. |
| `refresh()` | no | Renews tokens; resolves `true` when the session is still valid. |
| `getToken()` | no | A bearer token for API calls, or `null`. |
| `onChange(listener)` | no | Reports changes from elsewhere, such as another tab. Returns an unsubscribe function. |

An adapter for Acme's single sign-on service, which keeps the session in another tab-aware client:

```ts
// app/auth/acme_sso_adapter.ts
import { type Abilities, type AuthAdapter, createSession } from 'kitr/auth'

interface AcmeSsoClient {
  currentUser(): Promise<{ id: string; email: string; role: 'admin' | 'member'; teamId: string } | null>
  login(options: { email: string }): Promise<void>
  logout(): Promise<void>
  accessToken(): Promise<string | null>
  onAuthStateChanged(listener: (user: unknown) => void): () => void
}

export function acmeSsoAdapter<TUser>(
  client: AcmeSsoClient,
  abilities?: Abilities<TUser, any>,
): AuthAdapter<TUser, { email: string }> {
  const toSession = (user: unknown) => (user ? createSession(user as TUser, abilities) : null)
  return {
    getSession: async () => toSession(await client.currentUser()),
    async signIn({ email }) {
      await client.login({ email })
      const session = toSession(await client.currentUser())
      if (!session) throw new Error('Single sign-on did not return a user')
      return session
    },
    signOut: () => client.logout(),
    getToken: () => client.accessToken(),
    onChange: (listener) => client.onAuthStateChanged((user) => listener(toSession(user))),
  }
}
```

Register it in the config like any adapter:

```ts
// config/auth.ts
import { defineConfig } from 'kitr/auth'
import { type User, abilities } from '#app/abilities'
import { acmeSsoAdapter } from '#app/auth/acme_sso_adapter'
import { ssoClient } from '#app/auth/sso_client'

export default defineConfig({ adapter: acmeSsoAdapter<User>(ssoClient, abilities) })
```

Use `createSession(user, abilities, { expiresAt })` to build sessions, so `can()` follows your abilities. When `onChange` and `signIn` report the same session, listeners still run once.

## Devtools

With [Devtools](/packages/devtools) installed, the Auth panel shows the session status (authenticated or anonymous), the user as JSON and `expiresAt`. Its badge reads `in` or `out`. Three actions run against the live app: Reload session (`auth.load()`), Refresh token (`auth.refresh()`) and Sign out. Every sign-in and sign-out is logged on the timeline as `signed in` or `signed out`, with the user.

## Next steps

- [API reference](/packages/auth/api)
- [Router](/packages/router): `requireAuth()`, `can()` and route context
- [API routes](/packages/api): the routes `authMiddleware` protects
- [HTTP](/packages/http): sending the token and refreshing on `401`
- [Better Auth documentation](https://www.better-auth.com/docs)
- [Building a full-stack app](/docs/fullstack)


# Cache API

Source: https://kitr.dev/packages/cache/api

Every export of `kitr/cache`, `kitr/cache/provider`, read from the published type definitions. The [guide](/packages/cache) shows them in use.

## kitr/cache

### cached

```ts
function cached<Args extends unknown[], T>(cache: Cache, fn: (...args: Args) => Promise<T> | T, options: RememberOptions & {
  key: (...args: Args) => string;
}): (...args: Args) => Promise<T>;
```

Wrap a function so each distinct argument list is remembered under `key(...args)`.

### createCache

```ts
function createCache(config?: CacheConfig): Cache;
```

Build a cache without an app: what the provider binds, and what tests and scripts call directly.

### createMemoryCacheDriver

```ts
function createMemoryCacheDriver(): CacheDriver;
```

In-process cache with TTLs and tags. The default; fine for one server, wrong for several.

### useCache

```ts
function useCache(app: KitrApp): Cache;
```

The app's cache, from the container. Pass `ctx.app` in a controller; throws if the cache provider is not registered.

### defineConfig

```ts
const defineConfig: <const C extends CacheConfig>(config: C) => C;
```

Type the default export of `config/cache.ts`. Returns its argument unchanged.

### Cache

```ts
interface Cache {
  /** The parsed value, or `undefined` on a miss or after expiry. */
  get<T>(key: string): Promise<T | undefined>;
  /** Store a value as JSON (`undefined` is stored as `null`), with an optional ttl and tags. */
  set<T>(key: string, value: T, options?: RememberOptions): Promise<void>;
  /** Whether a live entry exists, including one holding `null`. */
  has(key: string): Promise<boolean>;
  /** Remove one entry. */
  delete(key: string): Promise<void>;
  /** Return the cached value, or run `fn`, store its result and return it. Concurrent calls share one run. */
  remember<T>(key: string, fn: () => Promise<T> | T, options?: RememberOptions): Promise<T>;
  /** Remove every entry tagged with any of `tags`, whatever its key. */
  invalidateTags(...tags: string[]): Promise<void>;
  /** Remove every entry from the driver. */
  clear(): Promise<void>;
  /** The driver underneath, for its `name` or a raw read. */
  readonly driver: CacheDriver;
}
```

The cache service bound as `cache` in the container: JSON values over a driver, with TTLs and tags.

### CacheConfig

```ts
interface CacheConfig {
  /** Where entries live. Default: `createMemoryCacheDriver()`. */
  driver?: CacheDriver;
  /** Prepended to every key, so several apps can share one Redis. */
  prefix?: string;
  /** Seconds, when `remember()` is called without a ttl. Default 300. */
  defaultTtl?: number;
}
```

The options in `config/cache.ts`, also accepted by `createCache()`.

### CacheDriver

```ts
interface CacheDriver {
  /** Shown in devtools and logs, e.g. `memory` or `redis`. */
  name: string;
  /** The stored string, or `undefined` when the key is missing or expired. */
  get(key: string): Promise<string | undefined>;
  /** `ttl` in seconds; `undefined` keeps the entry until deleted. */
  set(key: string, value: string, ttl?: number): Promise<void>;
  /** Remove one key and forget its tags. */
  delete(key: string): Promise<void>;
  /** Remove every key tagged with any of `tags`. */
  invalidateTags(tags: string[]): Promise<void>;
  /** Record the tags of a key so `invalidateTags` can find it. */
  tag(key: string, tags: string[]): Promise<void>;
  /** Remove every key and every tag. */
  clear(): Promise<void>;
}
```

What a cache backend implements: six async methods over string keys and string values.
Values arrive already serialised to JSON by the cache, and keys already carry the prefix.

### RememberOptions

```ts
interface RememberOptions {
  /** Seconds the entry lives. Default: the cache's `defaultTtl`. */
  ttl?: number;
  /** Labels to clear the entry by later with `invalidateTags()`. */
  tags?: string[];
}
```

Per-entry options for `set()`, `remember()` and `cached()`.

## kitr/cache/provider

### cacheProvider

```ts
const cacheProvider: import("@kitr/core").KitrProvider;
```

Binds `cache` from `config/cache.ts` (memory driver by default) on the server; does nothing in the browser.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Cache

Source: https://kitr.dev/packages/cache

Some reads are slow or expensive: a project report that joins six tables, a call to a rate-limited exchange-rate API, an invoice PDF summary rendered from a template. `kitr/cache` keeps the result for a while, so the next request gets it straight from memory or Redis. When the data changes, you clear every cached result about it with one tag instead of hunting down keys.

The package is a small layer of its own, not a wrapper: values are stored as JSON through a six-method driver, with a memory driver built in and a [Redis](https://redis.io/docs/latest/) driver a few lines away. On top of a plain key-value store it adds expiry times, tags, a key prefix, and `remember()`, which runs slow work once even when fifty requests ask at the same moment.

It runs on the server only. The provider does nothing in the browser. To cache what the API returns on the client, use [query](/packages/query), which already does.

The examples on this page follow Acme's project dashboard at `app.acme.com`: a report per project, a list of a team's open invoices, and an exchange rate used to show order totals in euros.

## Install

```sh
kitr add cache
```

What `kitr add` does:

- Adds the [server](/packages/server) package first if the project does not have it yet (and [logger](/packages/logger), which the server needs). The cache only runs on the server.
- Adds `@kitr/cache` to `dependencies` in `package.json` and installs it. Pass `--no-install` to skip the install.
- Adds `() => import('@kitr/cache/provider')` to `providers` and `'@kitr/cache'` to `packages` in `kitrrc.ts`. The provider binds `cache` in the container.
- Writes `config/cache.ts`, with `prefix` set to your package name.
- Adds a `## kitr: cache` section to `AGENTS.md`: expensive reads go through `cache.remember()` or `cached()`, `useCache(ctx.app)` in controllers, and writes invalidate by tag instead of guessing keys.

It adds no env variables, no scripts and asks no questions. No kit includes the cache, so every project adds it with this command.

`kitr remove cache` reverses every step above: it takes the provider and the package out of `kitrrc.ts`, deletes `config/cache.ts`, removes the dependency and the `AGENTS.md` section, then lists the files that still import `kitr/cache`.

## Configure

`kitr add cache` writes this file. In a project whose `package.json` is named `acme-app`, it reads:

```ts
// config/cache.ts
import { defineConfig } from 'kitr/cache'

export default defineConfig({
  // In-memory by default. For several instances pass a shared driver (Redis, Upstash) as `driver`.
  prefix: 'acme-app:',
  defaultTtl: 300,
})
```

| Option | Default | Description |
| --- | --- | --- |
| `driver` | `createMemoryCacheDriver()` | Where entries live. Any object that implements `CacheDriver`. See [Drivers](#drivers). |
| `prefix` | `''` | Prepended to every key before it reaches the driver, so several apps can share one Redis. |
| `defaultTtl` | `300` | Seconds an entry lives when `set()`, `remember()` or `cached()` is called without a `ttl`. |

The cache reads no env variables itself. A Redis driver usually reads `REDIS_URL`; see [Redis](#redis).

Config files are TypeScript, so you can choose values per environment in the file. To keep entries short-lived in development while you iterate on a report:

```ts
// config/cache.ts
import { defineConfig } from 'kitr/cache'

export default defineConfig({
  prefix: 'acme-app:',
  defaultTtl: process.env.NODE_ENV === 'production' ? 300 : 5,
})
```

## Cache your first slow read

On the server, get the cache with `useCache(app)` and wrap the slow call in `remember()`. This controller builds Acme's project report once every ten minutes:

```ts
// server/controllers/reports_controller.ts
import type { HttpContext } from 'kitr/api'
import { useCache } from 'kitr/cache'
import { buildProjectReport } from '#server/reports/project_report'

export default class ReportsController {
  async show({ app, params }: HttpContext<{ id: string }>) {
    return useCache(app).remember(
      `report:project:${params.id}`,
      () => buildProjectReport(params.id),
      { ttl: 600, tags: ['reports', `project:${params.id}`] },
    )
  }
}
```

Add the route next to the others:

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'
import ReportsController from '#server/controllers/reports_controller'

export const routes = defineRoutes((router) =>
  router.group({ prefix: '/api' }, (api) =>
    api.get('/projects/:id/report', [ReportsController, 'show'], { name: 'projects.report' }),
  ),
)
```

The first `GET /api/projects/42/report` runs `buildProjectReport('42')`, stores the result under `acme-app:report:project:42` for 600 seconds and returns it. Every request in the next ten minutes gets the stored copy without touching the database. After a write to project 42, clear the `project:42` tag (see [Clear entries by tag](#clear-entries-by-tag)) and the next request builds a fresh report.

## Get the cache on the server

The provider binds one cache as `cache` in the container. `useCache(app)` reads it, typed:

```ts
// server/controllers/invoices_controller.ts
import type { HttpContext } from 'kitr/api'
import { useCache } from 'kitr/cache'

export default class InvoicesController {
  async index({ app }: HttpContext) {
    const cache = useCache(app)
    return cache.get<{ id: string; total: number }[]>('invoices:open')
  }
}
```

`app.container.use('cache')` returns the same object; `useCache` is a shorter, typed spelling. In a background job, the job context carries the app:

```ts
// server/jobs/warm_reports.ts
import { useCache } from 'kitr/cache'
import { defineJob } from 'kitr/jobs'
import { buildProjectReport } from '#server/reports/project_report'

export const warmReportsJob = defineJob('warm-reports', {
  schedule: { every: '1h' },
  async run(_payload, { app }) {
    const cache = useCache(app)
    for (const id of ['42', '43']) {
      await cache.set(`report:project:${id}`, await buildProjectReport(id), {
        ttl: 3600,
        tags: ['reports', `project:${id}`],
      })
    }
  },
})
```

If the provider is not registered, `useCache` throws `[kitr] No binding named "cache". Did you add the package that provides it?`. Run `kitr add cache`, or check that `() => import('@kitr/cache/provider')` is still in `kitrrc.ts`. The same error appears in browser code, because the provider binds nothing on the client.

## Remember a result

`remember(key, fn, options)` returns the cached value when there is one. On a miss it runs `fn`, stores what it returns and returns that:

```ts
// server/reports/team_summary.ts
import type { Cache } from 'kitr/cache'
import { countOpenInvoices } from '#server/repositories/invoices'

export function teamSummary(cache: Cache, teamId: string) {
  return cache.remember(
    `summary:team:${teamId}`,
    async () => ({ teamId, openInvoices: await countOpenInvoices(teamId) }),
    { ttl: 120, tags: [`team:${teamId}`] },
  )
}

// await teamSummary(cache, 'design')
// => { teamId: 'design', openInvoices: 3 }   (runs countOpenInvoices)
// await teamSummary(cache, 'design')
// => { teamId: 'design', openInvoices: 3 }   (from the cache, nothing runs)
```

Four rules decide what `remember()` stores:

| `fn` returns or throws | Stored? | Next call |
| --- | --- | --- |
| A value, including `0`, `''`, `false` and `null` | Yes, for `ttl` seconds | Gets the stored value |
| `undefined` | No | Runs `fn` again |
| Throws or rejects | No; the error reaches every waiting caller | Runs `fn` again |
| Still running when another call arrives with the same key | Once | Waits for the same run |

The last row is the reason to prefer `remember()` over a `get()` then `set()` pair. When a popular entry expires, fifty requests can miss at the same moment. With `get()` and `set()`, all fifty rebuild the report. With `remember()`, the first call runs `fn` and the other forty-nine wait for its result:

```ts
// server/reports/warm.ts
import type { Cache } from 'kitr/cache'
import { buildProjectReport } from '#server/reports/project_report'

export async function loadReportForEveryone(cache: Cache) {
  const calls = Array.from({ length: 50 }, () =>
    cache.remember('report:project:42', () => buildProjectReport('42'), { ttl: 600 }),
  )
  return Promise.all(calls)
}
// buildProjectReport ran once; all 50 calls got its result.
```

Sharing a run works inside one server process. Two instances that miss together each run `fn` once.

A failure is not cached, so a database blip does not leave a broken answer in place for ten minutes. Every caller that was waiting on the failed run gets the same error, and the next call tries again:

```ts
// server/rates/eur_rate.ts
import type { Cache } from 'kitr/cache'
import { fetchRate } from '#server/rates/client'

export async function eurRate(cache: Cache): Promise<number | null> {
  try {
    return await cache.remember('rate:USD:EUR', () => fetchRate('USD', 'EUR'), { ttl: 3600 })
  } catch {
    // The rates API is down. Nothing was stored; the next call asks again.
    return null
  }
}
// await eurRate(cache)   // rates API down
// => null
// await eurRate(cache)   // rates API back
// => 0.92
```

## Choose a key

A key names one answer. Put every input that changes the answer into it, from the most general to the most specific:

```ts
// server/reports/keys.ts
export const reportKey = (projectId: string) => `report:project:${projectId}`
export const invoicesKey = (teamId: string, status: 'open' | 'paid', page: number) =>
  `invoices:team:${teamId}:${status}:page:${page}`
export const rateKey = (from: string, to: string) => `rate:${from}:${to}`
```

Keeping keys in one module means the code that reads an entry and the code that deletes it can't drift apart.

Anything that differs per user belongs in the key. Don't cache "my invoices" under `invoices:mine`: the first person to load it, say Ada, would have her invoices served to Grace. Use `invoices:user:${user.id}` instead, or cache the shared part and filter per user after the read.

The `prefix` from `config/cache.ts` is added in front of every key before it reaches the driver. You never write it yourself: `cache.get('rate:USD:EUR')` reads `acme-app:rate:USD:EUR` from the driver.

## Set expiry times

Every entry written through the cache expires. `ttl` is in seconds; without one, the entry gets `defaultTtl` from the config (300 unless you change it):

```ts
// server/rates/refresh.ts
import { useCache } from 'kitr/cache'
import type { KitrApp } from 'kitr/app'
import { fetchRate } from '#server/rates/client'

export async function refreshRates(app: KitrApp) {
  const cache = useCache(app)
  await cache.set('rate:USD:EUR', await fetchRate('USD', 'EUR'), { ttl: 3600 }) // one hour
  await cache.set('rate:USD:GBP', await fetchRate('USD', 'GBP')) // defaultTtl: 300 seconds
}
```

An entry is gone at exactly `ttl` seconds: a `get()` one millisecond before returns the value, a `get()` at the deadline returns `undefined`. The memory driver also sweeps expired entries that nobody reads again, at most once a minute, so a cache full of one-off keys does not grow forever.

Pick the ttl from how stale the answer may be, not from how slow it is to build. A team's invoice count can be two minutes old; an exchange rate for display can be an hour old; a permission check should not be cached at all. When you clear by tag after every write, a long ttl is safe, because the entry is replaced as soon as its data changes.

## Clear entries by tag

Tag an entry with what it is about when you store it. After a write, clear the tag, and every entry about that thing is gone, whatever its key:

```ts
// server/controllers/projects_controller.ts
import type { HttpContext } from 'kitr/api'
import { useCache } from 'kitr/cache'
import { updateProject } from '#server/repositories/projects'

export default class ProjectsController {
  async update({ app, params, body }: HttpContext<{ id: string }, {}, { name: string }>) {
    const project = await updateProject(params.id, body)
    await useCache(app).invalidateTags(`project:${params.id}`)
    return project
  }
}
```

The report under `report:project:42` and anything else tagged `project:42` are cleared. Entries tagged only `project:43` stay. `invalidateTags()` takes several tags at once and clears an entry that carries any of them:

```ts
// server/controllers/invoices_controller.ts
import type { HttpContext } from 'kitr/api'
import { useCache } from 'kitr/cache'
import { markInvoicePaid } from '#server/repositories/invoices'

export default class InvoicesController {
  async pay({ app, params }: HttpContext<{ id: string }>) {
    const invoice = await markInvoicePaid(params.id)
    await useCache(app).invalidateTags(`team:${invoice.teamId}`, `project:${invoice.projectId}`)
    return invoice
  }
}
```

A tag that matches nothing is not an error. With the memory driver, overwriting a key with `set()` drops the old value's tags, so a value written later is never cleared by tags that belonged to the one it replaced. The Redis driver below keeps a key in its old tag sets until those tags are cleared, which can clear a newer value early but never serves a stale one.

Tag by the records a result depends on (`project:42`, `team:design`) and by kind (`reports`, `invoices`). Kind tags let you clear a whole family after a deploy changes how it is built: `invalidateTags('reports')`.

Don't guess keys after a write with a loop of `delete()` calls. Lists, pages and summaries hide under many keys, and the one you forget serves stale data. Clear the tag instead.

## Wrap a function

`cached(cache, fn, options)` turns a function into one that remembers its results. Each distinct argument list gets its own entry, named by `options.key`:

```ts
// server/rates/exchange_rate.ts
import { type Cache, cached } from 'kitr/cache'
import { fetchRate } from '#server/rates/client'

export const exchangeRate = (cache: Cache) =>
  cached(cache, (from: string, to: string) => fetchRate(from, to), {
    key: (from, to) => `rate:${from}:${to}`,
    ttl: 3600,
    tags: ['rates'],
  })
```

Call it with the app's cache wherever you need a rate:

```ts
// server/controllers/orders_controller.ts
import type { HttpContext } from 'kitr/api'
import { useCache } from 'kitr/cache'
import { exchangeRate } from '#server/rates/exchange_rate'

export default class OrdersController {
  async total({ app }: HttpContext) {
    const rate = exchangeRate(useCache(app))
    const eur = await rate('USD', 'EUR') // fetches, stores under rate:USD:EUR
    await rate('USD', 'EUR') // from the cache
    return { totalEur: Math.round(1250 * eur) }
    // => { totalEur: 1150 }   with a rate of 0.92
  }
}
```

The wrapped function has the same arguments and returns a promise of the same result. It follows every `remember()` rule: one run for concurrent callers, `undefined` and errors not stored. Use `cached()` when a function is called from many places; use `remember()` inline when it is called from one.

Entries live in the driver, not in the wrapper, so building the wrapper per request costs nothing and every request shares the stored rates. Don't call `useCache(server.app)` at module level: the module loads before the server boots, and the provider has not bound `cache` yet.

## Read and write entries directly

The cache also works as a typed key-value store. Values go in and come out as JSON:

```ts
// server/teams/budget.ts
import { useCache } from 'kitr/cache'
import type { KitrApp } from 'kitr/app'

export async function budgetExample(app: KitrApp) {
  const cache = useCache(app)

  await cache.set('budget:team:design', { spent: 1200, limit: 5000 }, { ttl: 60, tags: ['team:design'] })

  await cache.get<{ spent: number; limit: number }>('budget:team:design')
  // => { spent: 1200, limit: 5000 }
  await cache.has('budget:team:design')
  // => true
  await cache.delete('budget:team:design')
  await cache.get('budget:team:design')
  // => undefined
}
```

| Method | Returns | Description |
| --- | --- | --- |
| `get<T>(key)` | `Promise<T \| undefined>` | The parsed value, or `undefined` on a miss or after expiry. |
| `set(key, value, { ttl, tags })` | `Promise<void>` | Store a value as JSON. Replaces any entry under the key, with its tags. |
| `has(key)` | `Promise<boolean>` | Whether a live entry exists, including one that holds `null`. |
| `delete(key)` | `Promise<void>` | Remove one entry. |
| `remember(key, fn, { ttl, tags })` | `Promise<T>` | Cached value, or run `fn` and store it. See [Remember a result](#remember-a-result). |
| `invalidateTags(...tags)` | `Promise<void>` | Remove every entry tagged with any of `tags`. |
| `clear()` | `Promise<void>` | Remove every entry from the driver. |
| `driver` | `CacheDriver` | The driver underneath. |

`get()` returns `undefined` for a miss and the stored value otherwise, so a stored `0`, `false` or `null` comes back as itself. Use `has()` when you need to know whether a key exists without reading it.

## Store values that survive JSON

Every value passes through `JSON.stringify` on the way in and `JSON.parse` on the way out. Plain objects, arrays, strings, numbers, booleans and `null` round-trip exactly. Other types change shape:

```ts
// server/orders/last_order.ts
import { useCache } from 'kitr/cache'
import type { KitrApp } from 'kitr/app'

export async function lastOrderExample(app: KitrApp) {
  const cache = useCache(app)

  await cache.set('order:last', { id: 'ord_1', placedAt: new Date('2026-03-01T09:00:00Z') })
  await cache.get('order:last')
  // => { id: 'ord_1', placedAt: '2026-03-01T09:00:00.000Z' }   a string, not a Date

  await cache.set('order:none', undefined)
  await cache.get('order:none')
  // => null
}
```

| Stored | Read back |
| --- | --- |
| `Date` | ISO string |
| `undefined` (as the whole value) | `null` |
| `undefined` inside an object | The key is missing |
| `Map`, `Set` | `{}` |
| `BigInt` | `set()` throws a `TypeError` |
| Class instance | Plain object, no methods |

Convert on the way out when you need the richer type: `new Date(order.placedAt)`. Or cache the plain data and build the object after the read.

## Drivers

A driver decides where entries live. The cache talks to it through six methods over strings, so swapping drivers changes nothing else in your code.

| Driver | Shared between instances | Survives a restart | Use for |
| --- | --- | --- | --- |
| Memory (default) | No | No | Development, tests, one server process |
| Redis | Yes | Yes | Production with more than one instance |

### Memory

The default. Nothing to install and no config: leave `driver` out of `config/cache.ts`. To pass it explicitly, for example to share one memory driver between two caches in a script:

```ts
// config/cache.ts
import { createMemoryCacheDriver, defineConfig } from 'kitr/cache'

export default defineConfig({
  driver: createMemoryCacheDriver(),
  prefix: 'acme-app:',
  defaultTtl: 300,
})
```

Each server process has its own copy, and it empties when the process restarts. Once you run two instances behind a load balancer, `invalidateTags()` on one instance leaves the other serving the old value until its ttl runs out. Move to a shared store before that happens.

### Redis

Install a Redis client. This example uses [ioredis](https://github.com/redis/ioredis):

```sh
pnpm add ioredis
```

Write the driver once, in its own file:

```ts
// server/cache/redis_driver.ts
import type { CacheDriver } from 'kitr/cache'
import { Redis } from 'ioredis'

export function createRedisCacheDriver(url: string): CacheDriver {
  const redis = new Redis(url)
  return {
    name: 'redis',
    get: async (key) => (await redis.get(key)) ?? undefined,
    async set(key, value, ttl) {
      if (ttl) await redis.set(key, value, 'EX', ttl)
      else await redis.set(key, value)
    },
    delete: async (key) => void (await redis.del(key)),
    async tag(key, tags) {
      await Promise.all(tags.map((t) => redis.sadd(`tag:${t}`, key)))
    },
    async invalidateTags(tags) {
      for (const t of tags) {
        const keys = await redis.smembers(`tag:${t}`)
        if (keys.length) await redis.del(...keys)
        await redis.del(`tag:${t}`)
      }
    },
    clear: async () => void (await redis.flushdb()),
  }
}
```

Use it in the config:

```ts
// config/cache.ts
import { defineConfig } from 'kitr/cache'
import { createRedisCacheDriver } from '#server/cache/redis_driver'

export default defineConfig({
  driver: createRedisCacheDriver(process.env.REDIS_URL ?? 'redis://localhost:6379'),
  prefix: 'acme-app:',
  defaultTtl: 300,
})
```

Add the connection string to `.env`:

```sh
REDIS_URL=redis://localhost:6379
```

Redis expires keys itself with `EX`, so a Redis cache needs no sweeping. See the [ioredis docs](https://github.com/redis/ioredis#readme) for TLS, clusters and Sentinel.

> **Warning**
> `clear()` on this driver runs `FLUSHDB`, which deletes every key in the Redis database, including other apps' entries and anything that is not a cache entry. Give the cache its own Redis database (`redis://localhost:6379/1`) or replace `clear` with a scan-and-delete over your prefix.

Tags are stored under `tag:<name>` without the prefix, so two apps that share one Redis and use the same tag name clear each other's entries. Give each app its own database, or put your app name in tag names (`acme-app:project:42`).

## Use the cache in production

- **More than one instance needs a shared driver.** With the memory driver, each instance has its own entries, and a tag cleared on one instance stays on the others.
- **The memory driver empties on deploy.** The first requests after a restart all miss. Warm the slowest entries from a job (see [Get the cache on the server](#get-the-cache-on-the-server)) if a cold start hurts.
- **A cache is not a store.** Anything in it can vanish at any time: a restart, an eviction, a `clear()`. Never keep the only copy of data in the cache.
- **Driver errors are not caught.** If Redis is down, `get()`, `set()` and `remember()` reject with the driver's error. Catch it in the caller when the page should still load without the cache.

## Devtools

When the [devtools](/packages/devtools) package is installed, the cache provider logs the driver it booted with to the `cache` channel at start-up, for example `driver: memory`. That line is the quickest way to confirm that production picked up the Redis driver.

## Testing

`createCache()` builds a cache with the memory driver and no app, which is all most tests need. Vitest's fake timers move the clock past a ttl without waiting:

```ts
// server/reports/team_summary.test.ts
import { createCache } from 'kitr/cache'
import { afterEach, describe, expect, it, vi } from 'vitest'

afterEach(() => {
  vi.useRealTimers()
})

describe('team summary cache', () => {
  it('builds once, serves from the cache, and rebuilds after a tag is cleared', async () => {
    const cache = createCache({ prefix: 'test:', defaultTtl: 60 })
    const countOpenInvoices = vi.fn(async (teamId: string) => (teamId === 'design' ? 3 : 0))
    const summary = (teamId: string) =>
      cache.remember(
        `summary:team:${teamId}`,
        async () => ({ teamId, openInvoices: await countOpenInvoices(teamId) }),
        { tags: [`team:${teamId}`] },
      )

    expect(await summary('design')).toEqual({ teamId: 'design', openInvoices: 3 })
    expect(await summary('design')).toEqual({ teamId: 'design', openInvoices: 3 })
    expect(countOpenInvoices).toHaveBeenCalledTimes(1)

    await cache.invalidateTags('team:design')
    await summary('design')
    expect(countOpenInvoices).toHaveBeenCalledTimes(2)
  })

  it('expires entries after the ttl', async () => {
    vi.useFakeTimers()
    const cache = createCache()
    await cache.set('rate:USD:EUR', 0.92, { ttl: 10 })
    vi.advanceTimersByTime(9_999)
    expect(await cache.get('rate:USD:EUR')).toBe(0.92)
    vi.advanceTimersByTime(1)
    expect(await cache.get('rate:USD:EUR')).toBeUndefined()
  })
})
```

Code that calls `useCache(app)` needs an app with the provider. `createTestApp` from [testing](/packages/testing) boots one with your config:

```ts
// server/reports/report_cache.test.ts
import { useCache } from 'kitr/cache'
import cacheProvider from 'kitr/cache/provider'
import { createTestApp } from 'kitr/testing'
import { expect, it } from 'vitest'

it('binds the cache from config', async () => {
  const app = await createTestApp({
    providers: [cacheProvider],
    config: { cache: { prefix: 'acme-test:' } },
  })
  const cache = useCache(app)
  await cache.set('report:project:42', { total: 12 })
  expect(await cache.driver.get('acme-test:report:project:42')).toBe('{"total":12}')
})
```

`createTestApp` boots the app with `environment: 'test'`, which the cache provider treats like the server. Only `environment: 'client'` makes it bind nothing. Each `createCache()` and each test app gets its own memory driver, so tests never see each other's entries.

## Extend

A driver is an object that implements `CacheDriver`: a `name` and six async methods over string keys and string values. The cache has already added the prefix to every key and serialised every value to JSON by the time the driver sees it.

| Member | Called by | Must |
| --- | --- | --- |
| `name` | devtools | Name the driver, e.g. `redis`. |
| `get(key)` | `get`, `has`, `remember` | Return the string, or `undefined` when missing or expired. |
| `set(key, value, ttl)` | `set`, `remember` | Store the string; expire it after `ttl` seconds (`undefined` means never). |
| `delete(key)` | `delete` | Remove the key. |
| `tag(key, tags)` | `set` with `tags` | Record that `key` carries each tag. |
| `invalidateTags(tags)` | `invalidateTags` | Remove every key that carries any of `tags`. |
| `clear()` | `clear` | Remove everything the driver holds. |

The Redis driver under [Redis](#redis) is a complete example. Drivers also compose. This one wraps another driver and counts hits and misses, which helps tune ttls:

```ts
// server/cache/counting_driver.ts
import type { CacheDriver } from 'kitr/cache'

export function countingDriver(inner: CacheDriver) {
  const stats = { hits: 0, misses: 0 }
  const driver: CacheDriver = {
    name: `counting(${inner.name})`,
    async get(key) {
      const value = await inner.get(key)
      if (value === undefined) stats.misses++
      else stats.hits++
      return value
    },
    set: (key, value, ttl) => inner.set(key, value, ttl),
    delete: (key) => inner.delete(key),
    tag: (key, tags) => inner.tag(key, tags),
    invalidateTags: (tags) => inner.invalidateTags(tags),
    clear: () => inner.clear(),
  }
  return { driver, stats }
}
```

Register it in the config like any other driver:

```ts
// config/cache.ts
import { createMemoryCacheDriver, defineConfig } from 'kitr/cache'
import { countingDriver } from '#server/cache/counting_driver'

export const cacheStats = countingDriver(createMemoryCacheDriver())

export default defineConfig({
  driver: cacheStats.driver,
  prefix: 'acme-app:',
  defaultTtl: 300,
})
```

`cacheStats.stats` now reads `{ hits: 41, misses: 3 }` after a busy minute. See [`CacheDriver`](/packages/cache/api#cachedriver) in the API reference for the exact signatures.

## Next steps

- [API reference](/packages/cache/api): every export with its signature.
- [Query](/packages/query): cache API responses in the browser.
- [Jobs](/packages/jobs): warm slow entries on a schedule.
- [Server](/packages/server): the runtime the cache provider binds into.
- [ioredis](https://github.com/redis/ioredis): the Redis client used in the driver above.


# Consent API

Source: https://kitr.dev/packages/consent/api

Every export of `kitr/consent`, `kitr/consent/react`, `kitr/consent/provider`, read from the published type definitions. The [guide](/packages/consent) shows them in use.

## kitr/consent

### createConsent

```ts
function createConsent(config?: ConsentConfig, app?: KitrApp): Consent;
```

Build a consent service backed by a cookie. The provider calls it with the app (for devtools
logging); tests and server code can call it without one.

### useConsent

```ts
function useConsent(app: KitrApp): Consent;
```

The consent service from an app's container. Not a hook; components use `useConsent()` from `kitr/consent/react`.

### defineConfig

```ts
const defineConfig: <const C extends ConsentConfig>(config: C) => C;
```

Types the default export of `config/consent.ts`.

### Consent

```ts
interface Consent {
  /** The record, with `decidedAt` unset while the banner should show. */
  get(): ConsentRecord;
  /** Has the visitor decided (for this version)? */
  decided(): boolean;
  /** Whether a category is granted for the current version. Always true for `necessary`. */
  has(category: ConsentCategory): boolean;
  /** Grant exactly these categories (plus `necessary`). */
  grant(categories: ConsentCategory[]): void;
  /** Grant every configured category. */
  acceptAll(): void;
  /** Decline everything but `necessary`. */
  rejectAll(): void;
  /** Forget the choice so the banner shows again. */
  reset(): void;
  /** Call `listener` after every change to the choice. Returns the unsubscribe function. */
  subscribe(listener: (record: ConsentRecord) => void): () => void;
  /** The categories from config, in order. */
  readonly categories: ConsentCategory[];
  /** The storage cookie that holds the record; `cookie.get(request.headers)` reads it on the server. */
  readonly cookie: CookieItem<ConsentRecord>;
}
```

The consent service bound as `consent` in the container. Reads and writes the visitor's choice.

### ConsentConfig

```ts
interface ConsentConfig {
  /** What the banner offers. Default `['analytics', 'marketing']`. */
  categories?: ConsentCategory[];
  /** Re-ask when this changes. Default 1. */
  version?: number;
  /** Cookie name. Default `consent`. */
  cookie?: string;
  /** Days the choice is kept. Default 365. */
  maxAge?: number;
  /** Which category analytics waits for. Default `analytics`; false never gates it. */
  analytics?: ConsentCategory | false;
  /** Which category error monitoring waits for. Default: none (monitoring runs; set `'analytics'` to gate it). */
  monitoring?: ConsentCategory | false;
}
```

Options for `config/consent.ts`: the categories offered, the version, the cookie and what to gate.

### ConsentRecord

```ts
interface ConsentRecord {
  /** Categories the visitor agreed to. `necessary` is always in. */
  granted: ConsentCategory[];
  /** ISO time of the choice; undefined until they chose. */
  decidedAt?: string;
  /** Bump `config.version` to ask everyone again. */
  version: number;
}
```

What a visitor agreed to, stored as JSON in the consent cookie.

### ConsentCategory

```ts
type ConsentCategory = 'necessary' | 'analytics' | 'marketing' | 'preferences' | (string & {});
```

A consent category. `necessary` is always granted; the others are whatever `config.categories` lists.

## kitr/consent/react

### useConsent

```ts
function useConsent(): {
  record: ConsentRecord;
  decided: boolean;
  has: (category: ConsentCategory) => boolean;
  categories: ConsentCategory[];
  grant: Consent['grant'];
  acceptAll: () => void;
  rejectAll: () => void;
  reset: () => void;
};
```

The consent record and the actions a banner needs; re-renders when the choice changes. The
server always sees "undecided" while the browser reads the cookie on its first render, so in
server-rendered apps render the banner only after mount.

## kitr/consent/provider

### consentProvider

```ts
const consentProvider: import("@kitr/core").KitrProvider;
```

Binds `consent` and gates the trackers: analytics stays queued until its category is granted
(and is disabled again when it is withdrawn); monitoring is gated only when `config.monitoring`
names a category. Put the provider after the analytics and monitoring ones in kitrrc.ts.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Consent

Source: https://kitr.dev/packages/consent

In much of the world you need a visitor's permission before you load analytics, marketing pixels or session replay. `kitr/consent` keeps one record per visitor of what they agreed to, by category, in a cookie that the server can read too. While a category is not granted, [analytics](/packages/analytics) keeps its calls in a queue and, if you ask it to, [monitoring](/packages/monitoring) drops its reports. Your banner is a few lines over `useConsent()`, so it looks like the rest of your app.

The examples on this page follow one scenario: Acme's app at `app.acme.com` asks Ada for consent on her first visit, holds Google Analytics until she agrees, loads a marketing pixel only for the `marketing` category, and lets Grace change her mind from the settings page.

`kitr/consent` runs in the browser: the provider only gates analytics and monitoring on the client. The record lives in a cookie made with [`kitr/storage`](/packages/storage), so server code can read it from the request. It is not a legal template: you decide the categories and the wording, and your lawyer decides whether they are enough.

## Install

```sh
kitr add consent
```

What `kitr add` does:

- Adds [storage](/packages/storage) first when the project does not have it, because the record is a storage cookie.
- Installs `@kitr/consent`.
- Adds `() => import('@kitr/consent/provider')` to the end of `providers` and `'@kitr/consent'` to `packages` in `kitrrc.ts`.
- Writes `config/consent.ts` (shown in [Configure](#configure)) and regenerates `config/index.ts`.
- Writes `app/components/consent-banner.tsx`, a banner with "Only necessary" and "Accept all" buttons, styled with Tailwind classes.
- Adds a `## kitr: consent` section to `AGENTS.md` telling coding agents that the banner is the one place consent is asked, never to call `analytics.enable()` by hand, and to check `useConsent().has('marketing')` before loading third-party scripts.

`kitr add consent` asks no questions and writes no env variables. To edit `package.json` without running the package manager, pass the global flag:

```sh
kitr add consent --no-install
```

No kit includes consent. It is a client package, so in a server-only project `kitr add consent` prints a warning and skips it.

`kitr remove consent` removes the provider, the `packages` entry, the dependency and the `AGENTS.md` section, and deletes `config/consent.ts`. It leaves `app/components/consent-banner.tsx` and the place you mounted it, which you delete by hand. Visitors keep their `consent` cookie until it expires.

## Configure

`kitr add consent` writes this file:

```ts
// config/consent.ts
import { defineConfig } from 'kitr/consent'

export default defineConfig({
  categories: ['analytics', 'marketing'],
  version: 1, // bump to ask everyone again
  analytics: 'analytics', // analytics waits for this category
  monitoring: false, // error reports are not gated
})
```

| Option | Default | Description |
| --- | --- | --- |
| `categories` | `['analytics', 'marketing']` | The categories your banner offers. `necessary` is always granted and never needs listing. `grant()` ignores any category not in this list. |
| `version` | `1` | The version of your consent text. A stored choice with another version counts as undecided, so bumping it asks everyone again. |
| `cookie` | `'consent'` | The cookie name, before the [storage](/packages/storage) prefix is added. |
| `maxAge` | `365` | Days the browser keeps the choice. |
| `analytics` | `'analytics'` | The category [analytics](/packages/analytics) waits for. `false` leaves analytics alone. |
| `monitoring` | `false` | The category [monitoring](/packages/monitoring) waits for. `false` (or leaving it out) never holds error reports back. |

The cookie is written with `SameSite=Lax`, the `maxAge` above, and the cookie defaults from `config/storage.ts` (`path` and `secure`). Its name gets the storage `prefix`, so with `prefix: 'acme-app:'` the browser stores `acme-app:consent`.

The record inside it is JSON:

```json
{ "granted": ["necessary", "analytics"], "decidedAt": "2026-11-07T09:30:00.000Z", "version": 1 }
```

`kitr add analytics` writes its config with `enabled` left at `true`. Before you ship a consent banner, set it to `false`:

```ts
// config/analytics.ts
import { defineConfig, googleAnalytics } from 'kitr/analytics'
import { env } from '#app/env'

export default defineConfig({
  adapters: env.VITE_GA_MEASUREMENT_ID
    ? [googleAnalytics({ measurementId: env.VITE_GA_MEASUREMENT_ID })]
    : [],
  enabled: false,
  globalProps: { app: env.VITE_APP_NAME },
})
```

> **Warning**
> With `enabled` left at `true`, analytics enables itself while the app boots, before the consent provider runs. That loads the vendor's script (`gtag.js`, Plausible or PostHog), which may set cookies, even though consent disables sending a moment later. Set `enabled: false` in `config/analytics.ts` so no tracking script loads before the visitor agrees.

## Show your first banner

`kitr add` wrote this banner:

```tsx
// app/components/consent-banner.tsx
import { useConsent } from 'kitr/consent/react'

/** Mount once in the root layout. Renders nothing once a choice is recorded. */
export function ConsentBanner() {
  const { decided, acceptAll, rejectAll } = useConsent()
  if (decided) return null
  return (
    <div role="dialog" aria-label="Cookie consent" className="fixed inset-x-0 bottom-0 flex flex-wrap items-center justify-center gap-3 border-t bg-background p-4 text-sm">
      <span>We use cookies for analytics. You can change your mind in settings.</span>
      <button type="button" className="rounded-md border px-3 py-1" onClick={rejectAll}>
        Only necessary
      </button>
      <button type="button" className="rounded-md bg-foreground px-3 py-1 text-background" onClick={acceptAll}>
        Accept all
      </button>
    </div>
  )
}
```

Mount it once, in the root layout. Keep the rest of your root route as it is and render the banner after the `<Outlet />`:

```tsx
// app/routes/__root.tsx
import { Outlet } from 'kitr/router'
import { ConsentBanner } from '#app/components/consent-banner'

// ...

function RootLayout() {
  return (
    <>
      <Outlet />
      <ConsentBanner />
    </>
  )
}
```

Open `app.acme.com` in a private window. The banner sits at the bottom of the page. Click "Accept all" and:

1. The banner disappears, because `decided` is now `true`.
2. A `consent` cookie holds `{ granted: ['necessary', 'analytics', 'marketing'], decidedAt, version: 1 }`.
3. The provider calls `analytics.enable()`, which loads the analytics scripts and sends every call that was queued since the page loaded, the first page view included.

Reload the page and the banner stays hidden: the choice is read back from the cookie. Click "Only necessary" instead and the cookie records `['necessary']`; analytics keeps queuing and never sends.

## Offer a choice per category

`grant()` records exactly the categories you pass, plus `necessary`. Use it for a banner with checkboxes:

```tsx
// app/components/consent-banner.tsx
import { useConsent } from 'kitr/consent/react'
import { useState } from 'react'

const labels: Record<string, string> = {
  analytics: 'Usage statistics, so we know which pages help',
  marketing: 'Marketing, so our ads reach people like you',
}

export function ConsentBanner() {
  const { decided, categories, grant, acceptAll, rejectAll } = useConsent()
  const [chosen, setChosen] = useState<string[]>([])
  if (decided) return null
  return (
    <div role="dialog" aria-label="Cookie consent">
      <p>Acme uses cookies. Pick what you allow.</p>
      {categories.map((category) => (
        <label key={category}>
          <input
            type="checkbox"
            checked={chosen.includes(category)}
            onChange={(e) =>
              setChosen((c) => (e.target.checked ? [...c, category] : c.filter((x) => x !== category)))
            }
          />
          {labels[category] ?? category}
        </label>
      ))}
      <button type="button" onClick={rejectAll}>Only necessary</button>
      <button type="button" onClick={() => grant(chosen)}>Save choice</button>
      <button type="button" onClick={acceptAll}>Accept all</button>
    </div>
  )
}
```

`categories` comes from `config/consent.ts`, so adding a category there adds a checkbox. What each action records:

| Call | `granted` afterwards |
| --- | --- |
| `acceptAll()` | `['necessary', 'analytics', 'marketing']` |
| `rejectAll()` | `['necessary']` |
| `grant(['analytics'])` | `['necessary', 'analytics']` |
| `grant(['analytics', 'chat'])` | `['necessary', 'analytics']`, because `chat` is not in `categories` |
| `grant([])` | `['necessary']`, same as `rejectAll()` |

Every one of them sets `decidedAt` to the current time, writes the cookie and notifies subscribers.

## Add a category

Categories are plain strings. Add one to `config/consent.ts` and it appears in `categories`, so a banner that maps over them shows it:

```ts
// config/consent.ts
import { defineConfig } from 'kitr/consent'

export default defineConfig({
  categories: ['analytics', 'marketing', 'preferences'],
  version: 2, // new category: ask everyone again
  analytics: 'analytics',
  monitoring: false,
})
```

Then check it where the feature lives. Here the projects list only remembers Linus's sort order when he allowed `preferences`:

```tsx
// app/features/projects/use-sort-order.ts
import { useConsent } from 'kitr/consent/react'
import { useEffect, useState } from 'react'

export function useSortOrder() {
  const { has } = useConsent()
  const remember = has('preferences')
  const [order, setOrder] = useState<'name' | 'updated'>('updated')
  useEffect(() => {
    if (!remember) return
    const saved = localStorage.getItem('acme:project-sort')
    if (saved === 'name' || saved === 'updated') setOrder(saved)
  }, [remember])
  const change = (next: 'name' | 'updated') => {
    setOrder(next)
    if (remember) localStorage.setItem('acme:project-sort', next)
  }
  return [order, change] as const
}
```

Bump `version` whenever you add a category, so people who already chose are asked about the new one.

## Hold analytics for a different category

By default analytics waits for `analytics`. Point it at another category, or turn the gate off:

```ts
// config/consent.ts
import { defineConfig } from 'kitr/consent'

export default defineConfig({
  categories: ['statistics', 'marketing'],
  version: 1,
  analytics: 'statistics',
  monitoring: false,
})
```

With `analytics: false`, consent never calls `analytics.enable()` or `disable()`. Use it when you run a cookieless service you are allowed to use without consent, and set `enabled: true` in `config/analytics.ts` again.

## Load a second tracker for one category

Some trackers belong to a different category from your page views, such as a marketing service that sees every event. Add its adapter only after that category is granted, with `analytics.use()`:

```tsx
// app/components/marketing-tracker.tsx
import { posthog } from 'kitr/analytics'
import { useAnalytics } from 'kitr/analytics/react'
import { useConsent } from 'kitr/consent/react'
import posthogJs from 'posthog-js'
import { useEffect } from 'react'

export function MarketingTracker() {
  const { has } = useConsent()
  const analytics = useAnalytics()
  const allowed = has('marketing')
  useEffect(() => {
    if (!allowed || analytics.adapters.some((a) => a.name === 'posthog')) return
    analytics.use(posthog(posthogJs, { apiKey: 'phc_acme_marketing' }))
  }, [allowed, analytics])
  return null
}
```

The adapter receives calls made after it was added. Withdrawing `marketing` does not remove it; if analytics itself stays enabled, the adapter keeps receiving events until the next page load. Gate such a tracker on the same category as analytics if that matters to you.

## Keep the choice for less time

Some regulators expect you to ask again after six months. Set `maxAge` in days, and rename the cookie if another app on the same domain already uses `consent`:

```ts
// config/consent.ts
import { defineConfig } from 'kitr/consent'

export default defineConfig({
  categories: ['analytics', 'marketing'],
  version: 1,
  cookie: 'acme_consent',
  maxAge: 180,
  analytics: 'analytics',
  monitoring: false,
})
```

When the cookie expires the browser deletes it, the record reads as undecided, and the banner shows again.

## Show the banner without a flash

On the server, the consent service has no cookie to read, so server-rendered HTML always contains the banner. For a visitor who already chose, the client then reads the cookie, renders nothing, and React reports a hydration mismatch while the banner flickers away. Render the banner only after the component has mounted:

```tsx
// app/components/consent-banner.tsx
import { useConsent } from 'kitr/consent/react'
import { useEffect, useState } from 'react'

export function ConsentBanner() {
  const { decided, acceptAll, rejectAll } = useConsent()
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])
  if (!mounted || decided) return null
  return (
    <div role="dialog" aria-label="Cookie consent">
      <p>We use cookies for analytics. You can change your mind in settings.</p>
      <button type="button" onClick={rejectAll}>Only necessary</button>
      <button type="button" onClick={acceptAll}>Accept all</button>
    </div>
  )
}
```

The server and the first client render both produce nothing, so hydration matches. Right after mount, the banner appears only for visitors who have not decided. In a single-page app (web `spa` mode), there is no server HTML and the generated banner works as it is.

## Check a category before loading a script

For a script that is not a kitr package, such as an ad pixel or a chat widget, check its category first. `useConsent()` re-renders when the choice changes, so the script loads the moment the visitor agrees:

```tsx
// app/components/marketing-pixel.tsx
import { useConsent } from 'kitr/consent/react'
import { useEffect } from 'react'

export function MarketingPixel() {
  const { has } = useConsent()
  const allowed = has('marketing')
  useEffect(() => {
    if (!allowed || document.getElementById('acme-pixel')) return
    const script = document.createElement('script')
    script.id = 'acme-pixel'
    script.async = true
    script.src = 'https://pixel.acme.com/p.js'
    document.head.appendChild(script)
  }, [allowed])
  return null
}
```

Mount it next to the banner. `has('necessary')` is always `true`; any other category is `true` only when granted in the current version.

Don't put the vendor's `<script>` tag straight into the root layout's `head`. It would load for every visitor before they answer.

## Let visitors change their mind

Visitors must be able to withdraw consent as readily as they gave it. Give your settings page a button that calls `reset()`, which deletes the cookie so the banner shows again:

```tsx
// app/routes/_app/settings/privacy.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useConsent } from 'kitr/consent/react'

export const Route = createFileRoute('/_app/settings/privacy')({
  component: PrivacySettings,
})

function PrivacySettings() {
  const { record, decided, has, grant, reset } = useConsent()
  return (
    <main>
      <h1>Privacy</h1>
      <p>
        {decided
          ? `You chose on ${new Date(record.decidedAt!).toLocaleDateString('en-US')}.`
          : 'You have not chosen yet.'}
      </p>
      <label>
        <input
          type="checkbox"
          checked={has('analytics')}
          onChange={(e) =>
            grant(
              record.granted.filter((c) => c !== 'analytics').concat(e.target.checked ? ['analytics'] : []),
            )
          }
        />
        Usage statistics
      </label>
      <button type="button" onClick={reset}>Ask me again</button>
    </main>
  )
}
```

When Grace unticks "Usage statistics", `grant()` records the remaining categories and the provider calls `analytics.disable()`. Calls stop going out and the queue is emptied. Scripts that already loaded stay in the page until the next full reload, because a browser cannot unload a script.

`reset()` sets the record back to undecided, removes the cookie and notifies subscribers. The provider sees that `analytics` is no longer granted and calls `analytics.disable()`, so nothing is sent until the visitor chooses again.

## Ask everyone again

When you add a vendor or change what a category covers, bump `version`:

```ts
// config/consent.ts
import { defineConfig } from 'kitr/consent'

export default defineConfig({
  categories: ['analytics', 'marketing'],
  version: 2, // added PostHog session replay to analytics
  analytics: 'analytics',
  monitoring: false,
})
```

A stored record with `version: 1` now reads as undecided: `decided` is `false`, `has('analytics')` is `false`, and the banner shows again. The old cookie stays until the visitor chooses, then it is overwritten. A cookie whose JSON has the wrong shape (for example `granted` that is not an array) is also treated as undecided.

## Gate error reports

Error reports can contain page content and who the visitor is, so some teams treat them like analytics. Name a category in `monitoring` to hold [monitoring](/packages/monitoring) back until it is granted:

```ts
// config/consent.ts
import { defineConfig } from 'kitr/consent'

export default defineConfig({
  categories: ['analytics', 'marketing'],
  version: 1,
  analytics: 'analytics',
  monitoring: 'analytics',
})
```

While the category is not granted:

- `captureException`, `captureMessage`, `addBreadcrumb` and `setTag` are dropped, not queued. Errors from before consent are never reported.
- `setUser(user)` is remembered but not sent. When the visitor grants the category, the remembered user is sent at once, so you never call `setUser()` twice.
- When the visitor withdraws, monitoring receives `setUser(null)` and drops reports again.

The default, `monitoring: false`, leaves monitoring alone: errors are reported whatever the visitor chose. Many teams treat crash reports as necessary for running the service; decide with whoever owns your privacy policy.

## Read the choice outside React

Outside components, read the service from the container. It has the same actions as the hook, plus `subscribe()` for changes:

```ts
// app/features/consent/track-choices.ts
import type { KitrApp } from 'kitr/app'

export function logConsentChanges(app: KitrApp) {
  const consent = app.container.use('consent')
  console.info('consent at start', consent.get())
  return consent.subscribe((record) => {
    console.info('consent changed', record.granted)
    // => consent changed ['necessary', 'analytics']
  })
}
```

| Member | Returns | Description |
| --- | --- | --- |
| `get()` | `ConsentRecord` | The current record. The same object until the choice changes, so it is safe in `useSyncExternalStore`. |
| `decided()` | `boolean` | Whether the visitor chose, for the current `version`. |
| `has(category)` | `boolean` | Whether a category is granted. Always `true` for `necessary`. |
| `grant(categories)` | `void` | Record exactly these categories plus `necessary`. |
| `acceptAll()` | `void` | Grant every configured category. |
| `rejectAll()` | `void` | Grant only `necessary`. |
| `reset()` | `void` | Forget the choice and delete the cookie. |
| `subscribe(listener)` | `() => void` | Call `listener(record)` after every `grant`, `acceptAll`, `rejectAll` and `reset` on this service. Returns the unsubscribe function. |
| `categories` | `ConsentCategory[]` | The configured categories. |
| `cookie` | `CookieItem<ConsentRecord>` | The [storage](/packages/storage) cookie item that holds the record. |

`kitr/consent` also exports a `useConsent(app)` function that returns this service. Despite the name it is not a hook; in components use `useConsent()` from `kitr/consent/react`.

## Read consent on the server

The record is a cookie, so a server function or loader can read it from the request with `consent.cookie.get(headers)`. Use it to leave a marketing tag out of the HTML entirely for visitors who did not agree:

```ts
// app/features/consent/read-consent.ts
import { createServerFn } from '@tanstack/react-start'
import { getRequest } from '@tanstack/react-start/server'
import { createConsent } from 'kitr/consent'
import consentConfig from '#config/consent'

const { cookie } = createConsent(consentConfig)

/** Runs on the server: the categories this visitor granted, or none if they have not chosen. */
export const readConsent = createServerFn({ method: 'GET' }).handler(() => {
  const record = cookie.get(getRequest().headers)
  const current = record.version === (consentConfig.version ?? 1) && Array.isArray(record.granted)
  return current && record.decidedAt ? record.granted : []
})
// => ['necessary', 'analytics'] for Ada, [] for a first visit
```

`cookie.get()` returns the stored record as it is, so check `version` yourself, as above. The cookie name includes the storage prefix, which the [storage](/packages/storage) provider sets on the server too, so the same `config/storage.ts` applies to both sides.

## Testing

Two things are worth testing: that your banner records the right choice, and that tracking waits for it. The test app needs `environment: 'client'`, because the provider only gates analytics in the browser. The DOM environment keeps cookies between tests, so clear them in `afterEach`.

```tsx
// app/components/consent-banner.test.tsx
import { fireEvent, screen, waitFor } from '@testing-library/react'
import { memoryAdapter } from 'kitr/analytics'
import { analyticsProvider } from 'kitr/analytics/provider'
import { consentProvider } from 'kitr/consent/provider'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { afterEach, describe, expect, it } from 'vitest'
import { ConsentBanner } from './consent-banner'

afterEach(() => {
  document.cookie = 'consent=; max-age=0; path=/'
})

describe('ConsentBanner', () => {
  it('holds analytics until Ada accepts', async () => {
    const memory = memoryAdapter()
    const app = await createTestApp({
      environment: 'client',
      providers: [analyticsProvider, consentProvider],
      config: {
        analytics: { adapters: [memory], enabled: false, pageViews: false },
        consent: { categories: ['analytics', 'marketing'] },
      },
    })
    const analytics = app.container.use('analytics')
    renderWithKitr(<ConsentBanner />, { app })

    analytics.track('project.created', { id: 'prj_42' })
    expect(memory.calls).toEqual([])

    fireEvent.click(screen.getByRole('button', { name: 'Accept all' }))

    expect(screen.queryByRole('dialog')).toBeNull()
    expect(app.container.use('consent').get().granted).toEqual(['necessary', 'analytics', 'marketing'])
    await waitFor(() =>
      expect(memory.calls).toEqual([{ type: 'track', args: ['project.created', { id: 'prj_42' }] }]),
    )
  })

  it('sends nothing when Ada picks only necessary', async () => {
    const memory = memoryAdapter()
    const app = await createTestApp({
      environment: 'client',
      providers: [analyticsProvider, consentProvider],
      config: { analytics: { adapters: [memory], enabled: false, pageViews: false } },
    })
    renderWithKitr(<ConsentBanner />, { app })

    fireEvent.click(screen.getByRole('button', { name: 'Only necessary' }))
    app.container.use('analytics').track('project.created', { id: 'prj_42' })

    expect(app.container.use('consent').has('analytics')).toBe(false)
    expect(app.container.use('analytics').enabled).toBe(false)
    expect(memory.calls).toEqual([])
  })
})
```

The test uses the generated banner. If you added the mount guard from [Show the banner without a flash](#show-the-banner-without-a-flash), `renderWithKitr` runs the effect for you, so the same test passes.

For logic that only needs the record, `createConsent()` builds a service with no app. It reads and writes `document.cookie`, so it behaves exactly as in the browser:

```ts
// app/features/consent/consent.test.ts
import { createConsent } from 'kitr/consent'
import { afterEach, expect, it } from 'vitest'

afterEach(() => {
  document.cookie = 'consent=; max-age=0; path=/'
})

it('asks again after the version is bumped', () => {
  createConsent({ version: 1 }).acceptAll()
  expect(createConsent({ version: 1 }).decided()).toBe(true)
  expect(createConsent({ version: 2 }).decided()).toBe(false)
})
```

Run tests that touch `document` in a DOM environment (`happy-dom` or `jsdom`).

## Devtools

With [devtools](/packages/devtools) installed, every choice is logged under the `consent` channel as `decided`, with the record as data. Filter the Log panel by `consent` to see what was granted and when. The Analytics panel shows whether analytics is enabled or still queued, and its Enable and Disable actions let you check both states without clearing cookies.

## Next steps

- [API reference](/packages/consent/api) for every export and type.
- [Analytics](/packages/analytics) for what is held until consent.
- [Monitoring](/packages/monitoring) for the error reports you can gate.
- [Storage](/packages/storage) for the cookie the record lives in.
- [European Data Protection Board guidelines on consent](https://www.edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-052020-consent-under-regulation-2016679_en) for what a valid choice requires.


# Database API

Source: https://kitr.dev/packages/db/api

Every export of `kitr/db`, read from the published type definitions. The [guide](/packages/db) shows them in use.

## kitr/db

### defineDb

```ts
function defineDb<T>(definition: DbDefinition<T>): DbDefinition<T>;
```

Declares how the app connects to its database, in `config/db.ts`. Returns the definition
unchanged; it exists so `disconnect` and `onReady` receive the client type `connect` returns.

### useDb

```ts
function useDb<T>(app: KitrApp): T;
```

Returns the connected client from an app's container, typed as `T`: `useDb<AppDb>(ctx.app)`.
Throws when the app has no `db` binding, or when an async `connect` has not finished (call it after `app.boot()`).

### dbProvider

```ts
const dbProvider: KitrProvider;
```

The provider `kitr add db` puts in `kitrrc.ts`. It binds `db` in the container from `config/db.ts`,
connects during boot, runs `onReady` when the server is ready and `disconnect` on shutdown.

### defineConfig

```ts
const defineConfig: <const C extends DbDefinition<any>>(config: C) => C;
```

Untyped alias of `defineDb` for the `defineConfig` convention; prefer `defineDb`, which infers the client type.

### DbDefinition

```ts
interface DbDefinition<T> {
  /** Opens the connection and returns the client. Runs once during `app.boot()`; a rejection fails boot. */
  connect: (app: KitrApp) => T | Promise<T>;
  /** Closes the client when the server shuts down (SIGINT, SIGTERM or `server.close()`). */
  disconnect?: (db: T, app: KitrApp) => void | Promise<void>;
  /** Runs once the server is ready to serve, after boot. Use it to check for pending migrations or warm a pool. */
  onReady?: (db: T, app: KitrApp) => void | Promise<void>;
}
```

kitr ships no ORM. `defineDb` binds whatever you use (Drizzle, Prisma, Kysely,
a raw pool) as `db` in the container with connect/disconnect in the lifecycle.

```ts
// config/db.ts
export default defineDb({ connect: () => drizzle(process.env.DATABASE_URL!), disconnect: (db) => db.$client.end() })
```

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Database

Source: https://kitr.dev/packages/db

Orders, invoices, projects, teams: almost every app keeps its data in a database. `kitr/db` opens the connection when your app starts, hands the same client to every controller, action and job, and closes it cleanly when the server stops. It ships no ORM. You bring [Drizzle](https://orm.drizzle.team), [Prisma](https://www.prisma.io/docs), [Kysely](https://kysely.dev) or a plain [`pg`](https://node-postgres.com) pool, and kitr runs it inside the [app lifecycle](/docs/configuration).

It runs on the server only. If you only need to keep data in the browser or on a device, use [storage](/packages/storage) instead.

This guide follows Acme's app at `app.acme.com`: a Postgres database with `orders` and `projects` tables, read through Drizzle.

## Install

```sh
kitr add db
```

What `kitr add` does:

- Adds the [server](/packages/server) package first if the project does not have it yet.
- Installs `@kitr/db` (you use it through `kitr/db`).
- Adds `() => import('@kitr/db')` to `providers` in `kitrrc.ts`.
- Adds `'@kitr/db'` to `packages` in `kitrrc.ts`.
- Appends `DATABASE_URL=postgres://localhost:5432/app` under a `# Database` comment to `.env.example`, and to `.env` when it exists.
- Writes `config/db.ts` (shown under Configure). An existing file is left alone.
- Regenerates `config/index.ts`, the config list the standalone server imports.
- Adds a `## kitr: db` section to `AGENTS.md`: "`config/db.ts` connects the ORM; controllers and actions read it with `useDb<AppDb>(ctx.app)` or `ctx.app.container.use('db')`. Migrations are the ORM's own tooling."

`kitr add db` asks no questions. Pass `--dry-run` to print the changes without writing them, or `--no-install` to skip the package manager run.

The `server` kit (`kitr new acme-api --kit server`) already includes db. `kitr remove db` reverses every step above and deletes `config/db.ts`. It leaves your ORM packages and schema files in place.

## Configure

`kitr add db` writes this file. It connects nothing yet: `connect` returns an empty object until you fill in your ORM.

```ts
// config/db.ts
import { defineDb } from 'kitr/db'

// Example with Drizzle + postgres.js: `pnpm add drizzle-orm postgres`
// import { drizzle } from 'drizzle-orm/postgres-js'
// import postgres from 'postgres'

export default defineDb({
  connect: async () => {
    // const client = postgres(process.env.DATABASE_URL!)
    // return drizzle(client)
    return {} as unknown
  },
  // disconnect: (db) => db.$client.end(),
})
```

`defineDb` takes three functions. Each receives the app, so you can read `app.environment`, `app.isProduction` or another service from `app.container`.

| Option | Default | Description |
| --- | --- | --- |
| `connect(app)` | required | Opens the connection and returns the client. Runs once, during `app.boot()`. If it throws or rejects, boot fails with that error. |
| `disconnect(db, app)` | none | Closes the client. Runs when the server shuts down: on `SIGINT`, `SIGTERM` or `server.close()`. |
| `onReady(db, app)` | none | Runs once after boot, when the server starts serving. Use it to check for pending migrations. |

| Variable | Used for |
| --- | --- |
| `DATABASE_URL` | The connection string your `connect` reads. `kitr add` writes `postgres://localhost:5432/app` as the example value. |

`kitr/db` also exports `defineConfig`, the same identity helper every package has. Prefer `defineDb`: it infers the client type from `connect`, so `disconnect` and `onReady` receive a typed `db`.

## Connect with Drizzle

Install Drizzle and the postgres.js driver:

```sh
pnpm add drizzle-orm postgres
pnpm add -D drizzle-kit
```

Describe the tables. The schema is plain Drizzle; kitr does not read it.

```ts
// server/db/schema.ts
import { integer, pgTable, text, timestamp } from 'drizzle-orm/pg-core'

export const projects = pgTable('projects', {
  id: text('id').primaryKey(),
  teamId: text('team_id').notNull(),
  name: text('name').notNull(),
})

export const orders = pgTable('orders', {
  id: text('id').primaryKey(),
  teamId: text('team_id').notNull(),
  customerEmail: text('customer_email').notNull(),
  totalCents: integer('total_cents').notNull(),
  createdAt: timestamp('created_at').defaultNow().notNull(),
})
```

Then fill in `config/db.ts`. Export the client type as `AppDb` so the rest of the app can ask for it by name.

```ts
// config/db.ts
import { drizzle } from 'drizzle-orm/postgres-js'
import postgres from 'postgres'
import { defineDb } from 'kitr/db'
import * as schema from '#server/db/schema'

const createDb = () => drizzle(postgres(process.env.DATABASE_URL!), { schema })

/** The client every controller and action gets from useDb<AppDb>(). */
export type AppDb = ReturnType<typeof createDb>

export default defineDb({
  connect: () => createDb(),
  disconnect: (db) => db.$client.end(),
})
```

Point `DATABASE_URL` in `.env` at a running database:

```sh
DATABASE_URL=postgres://ada@localhost:5432/acme
```

Start the server with `kitr dev`. The provider calls `connect` during boot, before the first request. If Postgres is not running, the server does not start, and the log shows the driver's own error, such as `ECONNREFUSED`.

## Query from a controller

In a controller, `ctx.app` is the app for the current request. Pass it to `useDb` with your client type:

```ts
// server/controllers/orders_controller.ts
import { desc, eq } from 'drizzle-orm'
import type { HttpContext } from 'kitr/api'
import { useDb } from 'kitr/db'
import type { AppDb } from '#config/db'
import { orders } from '#server/db/schema'

export default class OrdersController {
  async index({ app, params }: HttpContext<{ teamId: string }>) {
    const db = useDb<AppDb>(app)
    return db
      .select()
      .from(orders)
      .where(eq(orders.teamId, params.teamId))
      .orderBy(desc(orders.createdAt))
  }
}
```

Register the route as usual with [api](/packages/api):

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'
import OrdersController from '#server/controllers/orders_controller'

export const routes = defineRoutes((router) =>
  router.get('/api/teams/:teamId/orders', [OrdersController, 'index']),
)
```

A request returns the rows as JSON:

```sh
curl http://localhost:3001/api/teams/team_acme/orders
```

```json
[{ "id": "ord_1", "teamId": "team_acme", "customerEmail": "grace@acme.com", "totalCents": 4900, "createdAt": "2026-11-02T09:14:00.000Z" }]
```

The request app is a fork of the root app. It shares the root's singletons, so every request gets the same pooled client, not a new connection.

## Query from an action

On the server, an [action](/packages/actions) handler has no `ctx`. Get the request's app with `useRequestApp` from `kitr/server`, falling back to the root app:

```ts
// app/actions/projects/rename.ts
import { eq } from 'drizzle-orm'
import { z } from 'zod'
import { defineAction } from 'kitr/actions'
import { useDb } from 'kitr/db'
import { useRequestApp } from 'kitr/server'
import { app } from '#app/app'
import type { AppDb } from '#config/db'
import { projects } from '#server/db/schema'

export const renameProject = defineAction('projects.rename', {
  input: z.object({ id: z.string(), name: z.string().min(2) }),
  effects: (project) => ({ invalidate: [['projects', 'list']], set: [{ key: ['projects', 'detail', project.id], data: project }] }),
  handler: async ({ input }) => {
    const db = useDb<AppDb>(useRequestApp(app))
    const [project] = await db
      .update(projects)
      .set({ name: input.name })
      .where(eq(projects.id, input.id))
      .returning()
    return project
  },
})
```

The handler only runs on the server, so the database driver never reaches the browser bundle. Don't import `config/db.ts` into a component; import it from server code and actions only.

## Query from a service or job

Code that runs outside a request, such as a scheduled [job](/packages/jobs) or a script, has the root app. Pass it to `useDb` directly:

```ts
// server/services/revenue.ts
import { eq, sum } from 'drizzle-orm'
import type { KitrApp } from 'kitr/app'
import { useDb } from 'kitr/db'
import type { AppDb } from '#config/db'
import { orders } from '#server/db/schema'

/** Total revenue for one team, in cents. */
export async function teamRevenue(app: KitrApp, teamId: string): Promise<number> {
  const db = useDb<AppDb>(app)
  const [row] = await db
    .select({ total: sum(orders.totalCents) })
    .from(orders)
    .where(eq(orders.teamId, teamId))
  return Number(row?.total ?? 0)
}
```

Taking `app` as a parameter keeps the function testable: a test passes an app with a fake client (see Testing).

## Read the client without a type

`useDb<T>(app)` is a typed shortcut for `app.container.use('db')`. Both return the same object:

```ts
// server/controllers/health_controller.ts
import type { HttpContext } from 'kitr/api'

export default class HealthController {
  async show({ app }: HttpContext) {
    const db = app.container.use('db') // typed as unknown
    return { ok: db !== undefined }
  }
}
```

`useDb` only casts; it does not check the shape. If `AppDb` and `connect` drift apart, TypeScript catches it only when `AppDb` is derived from `connect`, as in the Drizzle example above. Don't write the type by hand.

When the container has no `db` binding, both throw `[kitr] No binding named "db". Did you add the package that provides it?`. That means the provider is missing from `providers` in `kitrrc.ts`, or the code runs on an app that was created without it.

## Await the client before boot finishes

`connect` usually returns a promise. The provider resolves it during `app.boot()`, so `useDb` is synchronous everywhere after boot: in controllers, actions and jobs. Code that runs before boot completes, such as another provider's `register`, must await the binding instead:

```ts
// app/providers/project_stats.ts
import { defineProvider } from 'kitr/app'
import type { AppDb } from '#config/db'
import { projects } from '#server/db/schema'

export default defineProvider({
  name: 'projectStats',
  register(app) {
    app.container.singleton('projectStats', async (container) => {
      const db = (await container.make('db')) as AppDb
      return { count: async () => (await db.select().from(projects)).length }
    })
  },
})
```

Calling `useDb` while `connect` is still pending throws `[kitr] Binding "db" has an async factory; await container.make('db') before use('db').`

## Connect other ORMs

The provider calls whatever `connect` returns "the client". Any library works. Each one below follows the same steps: install, `config/db.ts`, `.env`, the library's own docs.

### Prisma

```sh
pnpm add @prisma/client
pnpm add -D prisma
```

```ts
// config/db.ts
import { PrismaClient } from '@prisma/client'
import { defineDb } from 'kitr/db'

const createDb = () => new PrismaClient()
export type AppDb = ReturnType<typeof createDb>

export default defineDb({
  connect: async () => {
    const prisma = createDb()
    await prisma.$connect()
    return prisma
  },
  disconnect: (prisma) => prisma.$disconnect(),
})
```

Prisma reads `DATABASE_URL` from `.env` through `schema.prisma`. Calling `$connect()` in `connect` makes a bad URL fail boot instead of the first query. See the [Prisma Client docs](https://www.prisma.io/docs/orm/prisma-client).

### Kysely

```sh
pnpm add kysely pg
pnpm add -D @types/pg
```

```ts
// config/db.ts
import { Kysely, PostgresDialect } from 'kysely'
import { Pool } from 'pg'
import { defineDb } from 'kitr/db'
import type { Database } from '#server/db/types'

export type AppDb = Kysely<Database>

export default defineDb({
  connect: (): AppDb =>
    new Kysely<Database>({
      dialect: new PostgresDialect({ pool: new Pool({ connectionString: process.env.DATABASE_URL }) }),
    }),
  disconnect: (db) => db.destroy(),
})
```

`Database` is your table interface, written by hand or generated with `kysely-codegen`. See the [Kysely docs](https://kysely.dev/docs/getting-started).

### A plain pg pool

```sh
pnpm add pg
pnpm add -D @types/pg
```

```ts
// config/db.ts
import { Pool } from 'pg'
import { defineDb } from 'kitr/db'

export type AppDb = Pool

export default defineDb({
  connect: async () => {
    const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 10 })
    await pool.query('select 1')
    return pool
  },
  disconnect: (pool) => pool.end(),
})
```

The `select 1` checks the URL during boot; a `Pool` opens no connection until its first query. See the [node-postgres pooling docs](https://node-postgres.com/features/pooling).

### SQLite with Drizzle

```sh
pnpm add drizzle-orm better-sqlite3
pnpm add -D @types/better-sqlite3
```

```ts
// config/db.ts
import Database from 'better-sqlite3'
import { drizzle } from 'drizzle-orm/better-sqlite3'
import { defineDb } from 'kitr/db'
import * as schema from '#server/db/schema'

const createDb = () => drizzle(new Database(process.env.DATABASE_URL ?? 'acme.db'), { schema })
export type AppDb = ReturnType<typeof createDb>

export default defineDb({
  connect: () => createDb(),
  disconnect: (db) => db.$client.close(),
})
```

Here `DATABASE_URL` is a file path such as `acme.db`. The schema uses `drizzle-orm/sqlite-core` tables instead of `pg-core`. See [Drizzle with SQLite](https://orm.drizzle.team/docs/get-started-sqlite).

## Validate DATABASE_URL at startup

`process.env.DATABASE_URL!` crashes deep inside the driver when the variable is missing. Declare it in the typed env instead, so the app refuses to start with a clear message:

```ts
// app/env.ts
import { createEnv, env as e } from 'kitr/env'

export const env = createEnv({
  public: {},
  server: {
    DATABASE_URL: e.url(),
  },
})
```

```ts
// config/db.ts
import { drizzle } from 'drizzle-orm/postgres-js'
import postgres from 'postgres'
import { defineDb } from 'kitr/db'
import { env } from '#app/env'
import * as schema from '#server/db/schema'

const createDb = () => drizzle(postgres(env.DATABASE_URL), { schema })
export type AppDb = ReturnType<typeof createDb>

export default defineDb({
  connect: () => createDb(),
  disconnect: (db) => db.$client.end(),
})
```

See [configuration](/docs/configuration) for how `createEnv` reads `.env` files.

## Change settings per environment

`connect` receives the app. Read `app.isProduction` or `app.environment` to size the pool or turn on TLS only where it matters:

```ts
// config/db.ts
import { drizzle } from 'drizzle-orm/postgres-js'
import postgres from 'postgres'
import { defineDb } from 'kitr/db'
import * as schema from '#server/db/schema'

const createDb = (production: boolean) =>
  drizzle(
    postgres(process.env.DATABASE_URL!, {
      max: production ? 20 : 5,
      ssl: production ? 'require' : false,
    }),
    { schema },
  )
export type AppDb = ReturnType<typeof createDb>

export default defineDb({
  connect: (app) => createDb(app.isProduction),
  disconnect: (db) => db.$client.end(),
})
```

`app.environment` is `'server'` for the running server and `'test'` in an app built by `createTestApp`.

## Check migrations when the server starts

`onReady` runs once, after boot, when the server starts serving: on `server.listen()`, or on the first `server.fetch()` outside tests. Use it to warn about, or refuse to run with, an outdated schema:

```ts
// config/db.ts
import { sql } from 'drizzle-orm'
import { drizzle } from 'drizzle-orm/postgres-js'
import postgres from 'postgres'
import { defineDb } from 'kitr/db'
import * as schema from '#server/db/schema'

const createDb = () => drizzle(postgres(process.env.DATABASE_URL!), { schema })
export type AppDb = ReturnType<typeof createDb>

const EXPECTED_MIGRATIONS = 12

export default defineDb({
  connect: () => createDb(),
  disconnect: (db) => db.$client.end(),
  onReady: async (db, app) => {
    const rows = await db.execute(sql`select count(*)::int as count from drizzle.__drizzle_migrations`)
    const applied = Number(rows[0]?.count ?? 0)
    if (applied < EXPECTED_MIGRATIONS) {
      if (app.isProduction) throw new Error(`Database is ${EXPECTED_MIGRATIONS - applied} migrations behind`)
      app.container.use('logger').warn(`Run pnpm db:migrate: ${EXPECTED_MIGRATIONS - applied} pending`)
    }
  },
})
```

`onReady` does not run in tests built with `createTestApp`, which only boots. The logger binding comes from [logger](/packages/logger).

## Run migrations

kitr has no migration runner. Your ORM's tools work unchanged, so their docs apply as written. Add scripts to `package.json`:

```json
{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "drizzle-kit migrate",
    "db:studio": "drizzle-kit studio"
  }
}
```

```ts
// drizzle.config.ts
import { defineConfig } from 'drizzle-kit'

export default defineConfig({
  schema: './server/db/schema.ts',
  out: './server/db/migrations',
  dialect: 'postgresql',
  dbCredentials: { url: process.env.DATABASE_URL! },
})
```

Run `pnpm db:migrate` in your deploy step, before the new server starts. With Prisma the commands are `prisma migrate dev` and `prisma migrate deploy`. See [Drizzle migrations](https://orm.drizzle.team/docs/migrations).

> **Warning**
> Don't run migrations from `connect` or `onReady` when more than one server instance starts at once. Two instances migrating the same database at the same time can leave it half-migrated. Run them once, from the deploy pipeline.

## Use a transaction

Transactions belong to your ORM. Get the client with `useDb` and call its own API:

```ts
// server/services/checkout.ts
import { eq } from 'drizzle-orm'
import type { KitrApp } from 'kitr/app'
import { useDb } from 'kitr/db'
import type { AppDb } from '#config/db'
import { orders, projects } from '#server/db/schema'

export async function placeOrder(app: KitrApp, input: { id: string; teamId: string; projectId: string }) {
  const db = useDb<AppDb>(app)
  return db.transaction(async (tx) => {
    const [project] = await tx.select().from(projects).where(eq(projects.id, input.projectId))
    if (!project) throw new Error(`Project ${input.projectId} not found`)
    const [order] = await tx
      .insert(orders)
      .values({ id: input.id, teamId: input.teamId, customerEmail: 'linus@acme.com', totalCents: 4_900 })
      .returning()
    return order
  })
}
```

If the callback throws, Drizzle rolls back both statements.

## Close the connection on shutdown

When the server receives `SIGINT` or `SIGTERM`, it stops accepting requests, then runs every provider's `shutdown` in reverse order. The db provider calls your `disconnect` there, so open queries finish before the pool closes:

```ts
// server/main.ts
import { mountRoutes } from 'kitr/api'
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'
import { routes } from './routes'

export const server = createServer({ providers: rc.providers, config })
mountRoutes(server, routes)

await server.listen({ port: 3001 })
// Ctrl-C logs "SIGINT received, shutting down", then calls disconnect(db, app).
```

If you leave `disconnect` out, the process still exits, but the database sees the connections drop instead of closing.

## Errors

These errors come from the app container and config when the database binding is wrong. Driver errors (`ECONNREFUSED`, authentication failures) pass through unchanged.

| Error | When | What to do |
| --- | --- | --- |
| `[kitr] Missing config "db". Create config/db.ts or pass it to createApp().` | The provider is registered but there is no `config/db.ts`, or a test passed no `db` config. | Run `kitr add db` again, or pass `config: { db: defineDb(...) }`. |
| `[kitr] No binding named "db". Did you add the package that provides it?` | `useDb` on an app without the db provider. | Add `() => import('@kitr/db')` to `providers` in `kitrrc.ts`, or `providers: [dbProvider]` in a test. |
| `[kitr] Binding "db" has an async factory; await container.make('db') before use('db').` | `useDb` before `app.boot()` finished. | Await `app.boot()` first, or use `await app.container.make('db')`. |
| The error `connect` threw | `connect` failed, for example the database is down. | Boot rejects with it and the server does not start. Fix the URL or start the database. |

## Testing

In a test, build the app with `createTestApp` from [testing](/packages/testing) and give `config` a `db` whose `connect` returns a fake. The provider binds it exactly as it binds the real client, so code under test calls `useDb` unchanged.

This tests `teamRevenue` from "Query from a service or job" against a fake client that answers one query:

```ts
// server/services/revenue.test.ts
import { dbProvider, defineDb } from 'kitr/db'
import { createTestApp } from 'kitr/testing'
import { describe, expect, it, vi } from 'vitest'
import type { AppDb } from '#config/db'
import { teamRevenue } from '#server/services/revenue'

describe('teamRevenue', () => {
  it('sums the team orders and closes the client on shutdown', async () => {
    const where = vi.fn(async () => [{ total: '16900' }])
    const fakeDb = { select: () => ({ from: () => ({ where }) }) } as unknown as AppDb
    const disconnect = vi.fn()

    const app = await createTestApp({
      providers: [dbProvider],
      config: { db: defineDb({ connect: () => fakeDb, disconnect }) },
    })

    expect(await teamRevenue(app, 'team_acme')).toBe(16_900)
    expect(where).toHaveBeenCalledOnce()

    await app.shutdown()
    expect(disconnect).toHaveBeenCalledWith(fakeDb, app)
  })
})
```

`createTestApp` boots the app, so `connect` has run and `useDb` works. It does not call `onReady`; call `await app.ready()` in the test when you want it.

To replace the client in an app that has already booted, bind a value over it. Every later `useDb`, including in request forks, returns the new value:

```ts
// test/orders.test.ts
import { dbProvider, defineDb, useDb } from 'kitr/db'
import { createTestApp } from 'kitr/testing'
import { expect, it } from 'vitest'

it('uses the stub bound after boot', async () => {
  const app = await createTestApp({
    providers: [dbProvider],
    config: { db: defineDb({ connect: () => ({ name: 'real' }) }) },
  })
  app.container.value('db', { name: 'stub' })
  expect(useDb<{ name: string }>(app)).toEqual({ name: 'stub' })
})
```

Bind the value after boot, not before: the provider's `register` replaces anything bound under `db` before it runs.

For queries you want to run for real, point `DATABASE_URL` at a throwaway test database in `.env.test` and run your migrations before the suite. For Postgres without a server, [PGlite](https://pglite.dev) runs in-process and Drizzle supports it through `drizzle-orm/pglite`.

To test a controller end to end, mount the routes on a server built with the fake db config and call it with `createTestClient(server)`. See [testing](/packages/testing).

## Next steps

- [API reference](/packages/db/api): `defineDb`, `DbDefinition`, `dbProvider`, `useDb`.
- [Drizzle ORM docs](https://orm.drizzle.team/docs/overview): schema, queries and migrations.
- [api](/packages/api): routes and controllers that read the database.
- [actions](/packages/actions): server functions your components call.
- [Getting started](/docs/getting-started): the server kit, which includes db.


# Desktop API

Source: https://kitr.dev/packages/desktop/api

Every export of `kitr/desktop`, `kitr/desktop/client`, `kitr/desktop/provider`, `kitr/desktop/tauri`, `kitr/desktop/electron`, `kitr/desktop/electron-main`, `kitr/desktop/electron-preload`, read from the published type definitions. The [guide](/packages/desktop) shows them in use.

## kitr/desktop

### desktop

```ts
const desktop: import("@kitr/core").PlatformFactory<DesktopOptions>;
```

macOS, Windows and Linux through a Tauri or Electron shell. The native project lives in
`platforms/<name>/`; the window loads the same client build the web platform ships.

```ts
platforms: { app: desktop({ shell: 'tauri' }) }
kitr dev app        # Vite on :3200 and the native window with HMR
kitr build app      # client build into dist/<name>/client, then installers
```

### DesktopOptions

```ts
interface DesktopOptions {
  /** `tauri` (Rust shell, small binaries) or `electron` (Chromium + Node). Default `tauri`. */
  shell: DesktopShell;
  /** Dev server port the shell loads from with `kitr dev <name>`. Default 3200. */
  port: number;
  /** Window title. Default the package name. */
  title?: string;
  width: number;
  height: number;
  minWidth?: number;
  minHeight?: number;
  /** Reverse-DNS bundle id. Default `com.example.<app>`. */
  appId?: string;
  /** Open devtools in dev. Default true. */
  devtools: boolean;
}
```

### DesktopShell

```ts
type DesktopShell = 'tauri' | 'electron';
```

## kitr/desktop/client

### desktopShell

```ts
function desktopShell(): 'tauri' | 'electron' | null;
```

`'tauri' | 'electron' | null`: which desktop shell the app runs in.

### isElectron

```ts
function isElectron(): boolean;
```

True in an Electron renderer (checks the kitr preload bridge, then the user agent).

### isTauri

```ts
function isTauri(): boolean;
```

True inside a Tauri webview (checks `window.__TAURI_INTERNALS__`), false in a browser.

## kitr/desktop/provider

### electronStorageDriver

```ts
function electronStorageDriver(): StorageDriver;
```

Storage over the `kitr:storage:*` IPC channels that `handleKitrIpc` serves from main.

### tauriStoreDriver

```ts
function tauriStoreDriver(file?: string): StorageDriver;
```

`@tauri-apps/plugin-store` (`kitr.json` in the app data dir) as a kitr storage driver.

### desktopProvider

```ts
const desktopProvider: import("@kitr/core").KitrProvider;
```

Runtime provider of the desktop platform. Inside a Tauri webview it registers the `platform`
driver on the Tauri APIs and a `storage` driver on the store plugin; inside Electron it uses
the kitr IPC channels that `handleKitrIpc` serves from main. In a plain browser it does nothing.

## kitr/desktop/tauri

### commandMutation

```ts
function commandMutation<TInput, TOutput>(command: (args: TInput) => Promise<TOutput>, options?: {
  effects?: MutationContract<TInput, TOutput>['effects'];
}): Omit<MutationContract<TInput, TOutput>, 'kind'>;
```

### commandQuery

```ts
function commandQuery<TInput, TOutput>(command: (args: TInput) => Promise<TOutput>, name: string): Omit<QueryContract<TInput, TOutput>, 'kind'>;
```

A query contract over a command, for `defineQuery(commandQuery(commands.greet, 'greet'))`.

### defineCommands

```ts
function defineCommands<C extends CommandMap>(): Commands<C>;
```

Typed `invoke`. Command names are the Rust function names (snake_case), argument keys are
the Rust parameter names in camelCase, exactly as Tauri expects.

```ts
type Commands = { greet: (args: { name: string }) => string }
export const commands = defineCommands<Commands>()
await commands.greet({ name: 'kitr' })
```

### emitTauri

```ts
function emitTauri<T>(event: string, payload?: T): Promise<void>;
```

Emit to the Rust side or other windows. No-op in a browser.

### isTauri

```ts
function isTauri(): boolean;
```

True inside a Tauri webview (checks `window.__TAURI_INTERNALS__`), false in a browser.

### useTauriEvent

```ts
function useTauriEvent<T = unknown>(event: string, handler: (payload: T) => void): void;
```

Subscribe to a Tauri event (`app.emit("progress", payload)` on the Rust side).

### CommandMap

```ts
type CommandMap = Record<string, (args: any) => unknown>;
```

A map of Rust `#[tauri::command]` functions: argument object → return type.
`defineCommands<Commands>()` gives you `commands.greet({ name })` typed end to end.

### Commands

```ts
type Commands<C extends CommandMap> = {
  [K in keyof C]: Parameters<C[K]>[0] extends undefined | void ? () => Promise<Awaited<ReturnType<C[K]>>> : (args: Parameters<C[K]>[0]) => Promise<Awaited<ReturnType<C[K]>>>;
};
```

## kitr/desktop/electron

### createIpcClient

```ts
function createIpcClient<S extends IpcSchema, E extends IpcEvents = {}>(key?: string): IpcClient<S, E>;
```

Renderer side: a typed client over the bridge the preload script exposed.

### isElectron

```ts
function isElectron(): boolean;
```

True in an Electron renderer (checks the bridge, then the user agent).

### IPC_BRIDGE_KEY

```ts
const IPC_BRIDGE_KEY = "kitrIpc";
```

### IpcBridge

```ts
interface IpcBridge {
  invoke(channel: string, ...args: unknown[]): Promise<unknown>;
  on(channel: string, listener: (...args: unknown[]) => void): () => void;
  send(channel: string, ...args: unknown[]): void;
}
```

### IpcClient

```ts
type IpcClient<S extends IpcSchema, E extends IpcEvents = {}> = {
  invoke<K extends keyof S & string>(channel: K, ...args: Parameters<S[K]>): Promise<Awaited<ReturnType<S[K]>>>;
  on<K extends keyof E & string>(channel: K, listener: (...args: Parameters<E[K]>) => void): () => void;
  send(channel: string, ...args: unknown[]): void;
  /** True when the preload bridge is present (running inside Electron). */
  readonly available: boolean;
};
```

### IpcEvents

```ts
type IpcEvents = Record<string, (...args: any[]) => void>;
```

Events pushed from main to renderer: `{ 'download.progress': (percent: number) => void }`

### IpcSchema

```ts
type IpcSchema = Record<string, (...args: any[]) => unknown>;
```

One schema shared by main, preload and renderer:

```ts
export type Ipc = {
  'files.open': (path: string) => Promise<string>
  'app.version': () => string
}
```
Main: `handleIpc<Ipc>(ipcMain, { 'files.open': async (_e, path) => readFile(path, 'utf8'), ... })`
Preload: `exposeIpc(contextBridge, ipcRenderer)`
Renderer: `const ipc = createIpcClient<Ipc>()` → `await ipc.invoke('files.open', '/tmp/a')`

## kitr/desktop/electron-main

Re-exports `node` unchanged, plus the following.

### createIpcEmitter

```ts
function createIpcEmitter<E extends IpcEvents>(target: () => WebContents | undefined): {
  emit<K extends keyof E & string>(channel: K, ...args: Parameters<E[K]>): void;
};
```

Typed sender for main → renderer events.

### createMainWindow

```ts
function createMainWindow(options?: MainWindowOptions): Promise<BrowserWindow>;
```

A BrowserWindow with the secure defaults (context isolation on, node integration off,
sandbox on), the preload script wired, and dev-vs-built loading handled.

### handleIpc

```ts
function handleIpc<S extends IpcSchema>(ipcMain: IpcMain, handlers: IpcHandlers<S>): () => void;
```

Register every handler of the schema on ipcMain. Returns a function that removes them.

### handleKitrIpc

```ts
function handleKitrIpc(ipcMain: IpcMain, app: App, options?: {
  storageFile?: string;
}): void;
```

The IPC handlers kitr's desktop provider relies on: storage (a JSON file in userData),
app version, open-external and quit. Call once in main.ts after `app.whenReady()`.

### projectFile

```ts
function projectFile(importMetaUrl: string, ...parts: string[]): string;
```

Resolve a file next to the project's package.json, for main.ts to find dist/<name>/client.

### registerAppScheme

```ts
function registerAppScheme(protocol: typeof import('electron').protocol): void;
```

Call at the top of main.ts (before the app is ready) so `app://` behaves like https:
absolute asset paths, fetch, service workers and cookies all work.

### serveClient

```ts
function serveClient(protocol: typeof import('electron').protocol, clientDir: string): void;
```

Serve the built client (`dist/<name>/client`) at `app://-/` with an SPA fallback to index.html.

### APP_SCHEME

```ts
const APP_SCHEME = "app";
```

The scheme the packaged renderer is served from. Register it before `app.whenReady()`.

### MainWindowOptions

```ts
interface MainWindowOptions extends BrowserWindowConstructorOptions {
  /** Dev server URL. kitr sets `ELECTRON_RENDERER_URL` for `kitr dev`. */
  devUrl?: string;
  /** The built client directory, served through `app://`. Default `../client` next to the main bundle. */
  clientDir?: string;
  /** Preload script path. Default `join(__dirname, '../preload/index.js')`. */
  preload?: string;
  /** Open devtools when loading the dev URL. Default true. */
  devtools?: boolean;
}
```

### IpcHandlers

```ts
type IpcHandlers<S extends IpcSchema> = {
  [K in keyof S]: (event: IpcMainInvokeEvent, ...args: Parameters<S[K]>) => ReturnType<S[K]> | Promise<Awaited<ReturnType<S[K]>>>;
};
```

## kitr/desktop/electron-preload

### exposeIpc

```ts
function exposeIpc(contextBridge: ContextBridge, ipcRenderer: IpcRenderer, options?: {
  key?: string;
  allow?: (channel: string) => boolean;
}): void;
```

Expose a minimal, channel-agnostic bridge. The renderer's `createIpcClient<Schema>()`
adds the types; nothing else from Node or Electron crosses the context boundary.

```ts
import { contextBridge, ipcRenderer } from 'electron'
exposeIpc(contextBridge, ipcRenderer)
```

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Desktop

Source: https://kitr.dev/packages/desktop

The desktop platform wraps your `app/` in a native window for Windows, macOS and Linux. Pick the shell: Tauri (a small Rust binary around the system webview) or Electron (a bundled Chromium, with electron-vite).

```ts
import { desktop } from 'kitr/desktop'

export default defineKitrConfig({
  platforms: {
    site: web({ mode: 'spa' }),
    app: desktop({ shell: 'tauri', title: 'Acme', width: 1200, height: 800 }),
  },
})
```

## Install

```sh
kitr add desktop app --shell tauri
```

This installs `@kitr/desktop` and the shell's tooling, adds the [router](/packages/router), [platform](/packages/platform) and [storage](/packages/storage) packages if missing, writes `platforms.app` into `kitrrc.ts`, registers the shell's drivers through `kitr/desktop/provider`, and scaffolds the native project under `platforms/app/`: `src-tauri/` for Tauri, or `main.ts`, `preload.ts` and `ipc.ts` for Electron.

## Run it

```sh
kitr dev app
kitr build app
```

`kitr dev app` starts the Vite dev server and opens the window on it. `kitr build app` builds the web bundle into `dist/app/client`, then runs `tauri build` or `electron-vite build` and `electron-builder` for installers. `kitr doctor` checks the Rust toolchain for Tauri.

## Options

| Option | Default | Description |
| --- | --- | --- |
| `shell` | `tauri` | `tauri` or `electron` |
| `port` | `3200` | Dev server port the window loads from |
| `title`, `width`, `height`, `minWidth`, `minHeight` | | The main window |
| `appId` | | Bundle identifier (reverse DNS) |
| `devtools` | `true` | Open devtools in development |

## Calling native code

**Tauri**: declare your Rust commands once and call them typed.

```ts
import { commandQuery, defineCommands } from 'kitr/desktop/tauri'

type Commands = { greet: (args: { name: string }) => string }
export const commands = defineCommands<Commands>()
export const greeting = commandQuery(commands.greet, 'greet')
```

**Electron**: one IPC schema shared by main, preload and the renderer (`platforms/app/ipc.ts`), `handleIpc()` in main, `exposeIpc()` in preload, and `createIpcClient<Ipc>()` in the app. Both degrade in a plain browser (`ipc.available`, `isTauri()`), so the same `app/` ships to the web unchanged.


# Devtools API

Source: https://kitr.dev/packages/devtools/api

Every export of `kitr/devtools`, `kitr/devtools/provider`, `kitr/devtools/ui`, read from the published type definitions. The [guide](/packages/devtools) shows them in use.

## kitr/devtools

### createDevtoolsHub

```ts
function createDevtoolsHub(options?: {
  maxEntries?: number;
}): DevtoolsHub$1;
```

The event bus and panel registry behind the overlay. The provider binds one per app in development;
create your own in tests to assert on what code logs. Keeps `maxEntries` (default 500) per channel.

### definePanel

```ts
function definePanel(panel: DevtoolsPanel$1): DevtoolsPanel$1;
```

Returns the panel unchanged, typed as a `DevtoolsPanel`. Use it in the module a provider's `devtools()` method imports.

### getDevtools

```ts
function getDevtools(app: KitrApp): DevtoolsHub | null;
```

The hub when devtools are active (development, client, `@kitr/devtools` added), else null.

### defineConfig

```ts
const defineConfig: <const C extends DevtoolsConfig>(config: C) => C;
```

Types the default export of `config/devtools.ts`.

### DevtoolsAction

```ts
interface DevtoolsAction {
  /** Unique id, used as the React key and in the command palette. */
  id: string;
  /** Button text and command palette label. */
  label: string;
  /** Runs when the button or palette entry is chosen. */
  run: (app: KitrApp) => MaybePromise<void>;
}
```

The devtools contract. Core only defines the shape; `@kitr/devtools` renders it.
Any provider can contribute by adding a `devtools(app)` method that returns panels.
Nothing here runs in production: the hub is only bound in development on the client.

### DevtoolsConfig

```ts
interface DevtoolsConfig {
  /** Default: development on the client. Set false to disable without removing the package. */
  enabled?: boolean;
  /** Where the trigger button sits. Default `bottom-left`. */
  position?: 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
  /** Keyboard shortcut, as `key` with ctrl/cmd+shift. Default `k`. */
  shortcutKey?: string;
  /** Entries kept per channel. Default 500. */
  maxEntries?: number;
  /** Open on first load. Default false. */
  openByDefault?: boolean;
}
```

Options for `config/devtools.ts`: whether the overlay is on, where its button sits, its shortcut and log size.

### DevtoolsEntry

```ts
interface DevtoolsEntry {
  /** Increasing id, unique for the page's lifetime. */
  id: number;
  /** The channel it was logged under, such as `http`, `analytics` or `logs`. */
  channel: string;
  /** `Date.now()` when it was logged. */
  time: number;
  /** Severity; the log view colours and filters by it. */
  level: 'debug' | 'info' | 'warn' | 'error';
  /** One-line summary shown in the list. */
  label: string;
  /** Anything extra, shown expanded under the line. */
  data?: unknown;
}
```

One line in the devtools log, recorded with `hub.log()`.

### DevtoolsHub

```ts
interface DevtoolsHub {
  /** Every registered panel, in tab order. */
  readonly panels: DevtoolsPanel[];
  /** Add a panel at runtime (providers normally use the `devtools()` method instead). */
  register(panel: DevtoolsPanel): () => void;
  /** Record an event (an HTTP request, an analytics call, a log line) under a channel. */
  log(channel: string, label: string, data?: unknown, level?: DevtoolsEntry['level']): void;
  /** Logged entries, oldest first; pass a channel to filter. */
  entries(channel?: string): DevtoolsEntry[];
  /** Empty the log, or one channel of it. */
  clear(channel?: string): void;
  /** Notified on new entries, panel changes and `notify()`; the overlay re-renders. */
  subscribe(listener: () => void): () => void;
  /** Tell the overlay that something it shows (session, cache) changed. */
  notify(): void;
}
```

The devtools service bound as `devtools` in development on the client: panels plus a shared event log.

### DevtoolsPanel

```ts
interface DevtoolsPanel {
  /** Unique id; registering another panel with the same id replaces this one. */
  id: string;
  /** Tab label. */
  label: string;
  /** Text or count shown next to the tab label. Re-read on every render. */
  badge?: (app: KitrApp) => string | number | null | undefined;
  /** The panel body. Return a React node; devtools re-renders it when the hub changes. */
  render: (app: KitrApp) => KitrNode;
  /** Buttons in the panel header and entries in the command palette. */
  actions?: DevtoolsAction[];
}
```

A tab in the devtools window, contributed by a provider's `devtools(app)` method or `hub.register()`.

## kitr/devtools/provider

### devtoolsProvider

```ts
const devtoolsProvider: import("@kitr/core").KitrProvider;
```

Development only. Binds the `devtools` hub, collects every provider's `devtools()` panels
and mounts the overlay. In production `register`/`wrap` are no-ops, and the kitr Vite plugin
aliases this module away entirely so nothing of it ships.

## kitr/devtools/ui

### Badge

```ts
function Badge({ children, tone }: {
  children: ReactNode;
  tone?: 'ok' | 'warn' | 'error' | 'muted' | 'info';
}): import("react").JSX.Element;
```

A small pill for counts and states. `tone` picks the colour: ok, warn, error, muted or info.

### Button

```ts
function Button({ children, onClick, title }: {
  children: ReactNode;
  onClick: () => void;
  title?: string;
}): import("react").JSX.Element;
```

A small button in the overlay's style.

### JsonView

```ts
function JsonView({ value, depth, open }: {
  value: unknown;
  depth?: number;
  open?: boolean;
}): import("react").JSX.Element;
```

Any value as an expandable tree, styled like the built-in panels. `open` expands the first level.

### KeyValue

```ts
function KeyValue({ rows }: {
  rows: Array<[
    string,
    unknown
  ]>;
}): import("react").JSX.Element;
```

A two-column table of `[key, value]` rows; each value renders as a `JsonView`.

### LogList

```ts
function LogList({ entries, empty }: {
  entries: DevtoolsEntry[];
  empty?: string;
}): import("react").JSX.Element;
```

A list of hub entries, newest last, with the data expandable.

### Toolbar

```ts
function Toolbar({ children }: {
  children: ReactNode;
}): import("react").JSX.Element;
```

A row of buttons, spaced like a panel's action bar.

### styles

```ts
const styles = "\n.kitr-dt{position:fixed;z-index:2147483000;font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;color:#e5e7eb}\n.kitr-dt *{box-sizing:border-box}\n.kitr-dt-trigger{position:fixed;z-index:2147483000;width:36px;height:36px;border-radius:999px;border:1px solid #374151;background:#111827;color:#a5b4fc;font:700 12px ui-monospace,monospace;cursor:pointer;box-shadow:0 2px 8px rgba(0,0,0,.4);display:flex;align-items:center;justify-content:center}\n.kitr-dt-trigger:hover{background:#1f2937}\n.kitr-dt-trigger-badge{position:absolute;top:-4px;right:-4px;background:#ef4444;color:#fff;border-radius:999px;font-size:10px;min-width:16px;height:16px;padding:0 4px;display:flex;align-items:center;justify-content:center}\n.kitr-dt-panel{position:fixed;left:0;right:0;bottom:0;height:var(--kitr-dt-height,45vh);background:#0b1020;border-top:1px solid #1f2937;display:flex;flex-direction:column;box-shadow:0 -4px 24px rgba(0,0,0,.5)}\n.kitr-dt-resize{height:4px;cursor:ns-resize;background:transparent}\n.kitr-dt-resize:hover{background:#4f46e5}\n.kitr-dt-tabs{display:flex;align-items:center;gap:2px;padding:4px 8px;border-bottom:1px solid #1f2937;overflow-x:auto}\n.kitr-dt-tab{background:transparent;border:0;color:#9ca3af;padding:4px 10px;border-radius:6px;cursor:pointer;font:inherit;white-space:nowrap;display:flex;gap:6px;align-items:center}\n.kitr-dt-tab:hover{color:#e5e7eb;background:#111827}\n.kitr-dt-tab-active{color:#fff;background:#1f2937}\n.kitr-dt-spacer{flex:1}\n.kitr-dt-body{flex:1;overflow:auto;padding:10px 12px}\n.kitr-dt-stack{display:flex;flex-direction:column;gap:14px}\n.kitr-dt-h{margin:0 0 6px;font-size:12px;color:#c7d2fe;text-transform:uppercase;letter-spacing:.04em}\n.kitr-dt-muted{color:#6b7280}\n.kitr-dt-table{border-collapse:collapse;width:100%}\n.kitr-dt-table td{padding:3px 8px 3px 0;vertical-align:top;border-bottom:1px solid #111827}\n.kitr-dt-key{color:#93c5fd;white-space:nowrap}\n.kitr-dt-table td.kitr-dt-key{width:1%;padding-right:16px}\n.kitr-dt-string{color:#86efac}.kitr-dt-number{color:#fcd34d}.kitr-dt-boolean{color:#f0abfc}.kitr-dt-undefined,.kitr-dt-object{color:#9ca3af}.kitr-dt-error{color:#fca5a5}\n.kitr-dt-toggle{background:none;border:0;color:#9ca3af;cursor:pointer;font:inherit;padding:0;display:inline-flex;align-items:center;gap:2px}\n.kitr-dt-indent{padding-left:14px;border-left:1px solid #1f2937;margin-left:3px}\n.kitr-dt-pre{margin:0;white-space:pre-wrap;word-break:break-all;max-height:120px;overflow:auto;color:#d1d5db}\n.kitr-dt-btn{background:#1f2937;border:1px solid #374151;color:#e5e7eb;border-radius:5px;padding:2px 8px;cursor:pointer;font:inherit;display:inline-flex;align-items:center;gap:4px}\n.kitr-dt-btn:hover{background:#374151}\n.kitr-dt-toolbar{display:flex;gap:6px;align-items:center;flex-wrap:wrap;margin-bottom:8px}\n.kitr-dt-input{background:#111827;border:1px solid #374151;color:#e5e7eb;border-radius:5px;padding:2px 8px;font:inherit;min-width:160px}\n.kitr-dt-badge{display:inline-block;border-radius:999px;padding:0 6px;font-size:10px;line-height:16px;background:#374151;color:#e5e7eb}\n.kitr-dt-badge-ok{background:#065f46;color:#d1fae5}.kitr-dt-badge-warn{background:#78350f;color:#fef3c7}.kitr-dt-badge-error{background:#7f1d1d;color:#fee2e2}.kitr-dt-badge-info{background:#1e3a8a;color:#dbeafe}\n.kitr-dt-log{display:flex;flex-direction:column}\n.kitr-dt-row{display:grid;grid-template-columns:90px 90px 1fr;gap:8px;padding:2px 0;border-bottom:1px solid #111827;align-items:start}\n.kitr-dt-row .kitr-dt-data{grid-column:3;padding-left:12px}\n.kitr-dt-time{color:#6b7280}.kitr-dt-channel{color:#a5b4fc}\n.kitr-dt-level-warn .kitr-dt-label{color:#fcd34d}.kitr-dt-level-error .kitr-dt-label{color:#fca5a5}.kitr-dt-level-debug .kitr-dt-label{color:#9ca3af}\n.kitr-dt-palette{position:fixed;inset:0;background:rgba(0,0,0,.5);display:flex;align-items:flex-start;justify-content:center;padding-top:12vh;z-index:2147483001}\n.kitr-dt-palette-box{width:min(560px,90vw);background:#0b1020;border:1px solid #374151;border-radius:10px;overflow:hidden;color:#e5e7eb;font:13px ui-monospace,monospace}\n.kitr-dt-palette-box input{width:100%;background:#111827;border:0;border-bottom:1px solid #374151;color:#fff;padding:10px 12px;font:inherit;outline:none}\n.kitr-dt-palette-item{padding:8px 12px;cursor:pointer;display:flex;justify-content:space-between}\n.kitr-dt-palette-item:hover,.kitr-dt-palette-item-active{background:#1f2937}\n";
```

The overlay's stylesheet as a string. The overlay injects it; panel bodies can use its `kitr-dt-*` classes.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Devtools

Source: https://kitr.dev/packages/devtools

When a page shows stale data or a button does nothing, the first question is what the app is doing right now: which route matched, what is in the query cache, who is signed in, which request failed. `kitr/devtools` answers it in the page itself. In development a small "k" button sits in a corner; open it and a panel shows the route, the cache, the session, saved values, errors, analytics calls and one log that every kitr package writes to. Your own providers can add panels and log lines with a few lines of code.

The examples on this page follow one scenario: Acme's app at `app.acme.com` has a cart for orders, and Ada wants to see what is in it, log each change, and empty it from a button while she builds the checkout.

`kitr/devtools` runs in the browser, in development only. It renders nothing on the server, binds nothing in production, and the `kitr()` Vite plugin leaves it out of production builds, so it adds no bytes for your users. It is a view onto kitr; for React component trees and network timing, keep using [React Developer Tools](https://react.dev/learn/react-developer-tools) and your browser's devtools next to it.

## Install

```sh
kitr add devtools
```

What `kitr add` does:

- Installs `@kitr/devtools`.
- Adds `() => import('@kitr/devtools/provider')` to `providers` and `'@kitr/devtools'` to `packages` in `kitrrc.ts`.
- Writes `config/devtools.ts` (shown in [Configure](#configure)) and regenerates `config/index.ts`.
- Adds a `## kitr: devtools` section to `AGENTS.md` telling coding agents how to open the overlay, to log with `getDevtools(app)?.log(...)`, and to add panels through a provider's `devtools()` method with the parts in `kitr/devtools/ui`.

`kitr add devtools` asks no questions and adds no env variables. To edit `package.json` without running the package manager, pass the global flag:

```sh
kitr add devtools --no-install
```

Every kit except `blank` and `server` includes devtools: `app`, `fullstack`, `saas`, `site`, `realtime`, `desktop` and `mobile`. It is a client package, so in a server-only project `kitr add devtools` prints a warning and skips it.

`kitr remove devtools` removes the provider, the `packages` entry, the dependency and the `AGENTS.md` section, and deletes `config/devtools.ts`. Calls to `getDevtools(app)?.log(...)` can stay: without the package they return `null` and do nothing. Panels you wrote in your own providers stay too, and are never shown.

## Configure

`kitr add devtools` writes this file:

```ts
// config/devtools.ts
import { defineConfig } from 'kitr/devtools'

/** Development only. The kitr() Vite plugin drops the provider from production builds. */
export default defineConfig({
  position: 'bottom-left',
  // ctrl/cmd+shift+<key> toggles the overlay; ctrl/cmd+shift+P opens the command palette.
  shortcutKey: 'k',
  maxEntries: 500,
})
```

| Option | Default | Description |
| --- | --- | --- |
| `enabled` | on in development in the browser | `false` turns devtools off without removing the package. `true` turns it on in any mode, but production builds still leave the provider out. |
| `position` | `'bottom-left'` | The corner for the "k" button: `'bottom-left'`, `'bottom-right'`, `'top-left'` or `'top-right'`. |
| `shortcutKey` | `'k'` | The key that toggles the panel together with <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>Shift</kbd>. |
| `maxEntries` | `500` | Log entries kept per channel. When a channel is full, its oldest entry is dropped. |
| `openByDefault` | `false` | Open the panel on first load. After that, the panel remembers whether you left it open. |

The panel also remembers, per browser, the tab you had open and the height you dragged it to. It keeps them in `localStorage` under `kitr:devtools`; delete that key to start fresh.

### Turn it off without removing it

Set `enabled: false` to hide the overlay and stop binding the hub, for example while you record a demo of `app.acme.com`:

```ts
// config/devtools.ts
import { defineConfig } from 'kitr/devtools'

export default defineConfig({
  enabled: false,
  position: 'bottom-left',
  shortcutKey: 'k',
  maxEntries: 500,
})
```

The package stays installed, so the panels come back when you remove the line. To keep a longer history while chasing a bug that takes many steps to reproduce, raise `maxEntries` instead; each channel keeps that many entries.

### Leave devtools out of a development build

The `kitr()` Vite plugin decides whether the provider is in the bundle at all. Production builds (`kitr build`, `vite build`) never include it. To leave it out in development too, for example while profiling, pass `devtools: false`:

```ts
// vite.config.ts
import { kitr } from 'kitr/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [kitr({ devtools: false })],
})
```

With the provider left out, `getDevtools(app)` returns `null` and every log call is skipped.

## Open the panel

Start the dev server with `kitr dev` and open the app. A round "k" button sits in the bottom-left corner. Click it, or press <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd>, and the panel opens along the bottom of the page.

- The tabs along the top are the panels. A tab's badge shows a count or a state, such as the number of errors in the log.
- The buttons under the tabs are the current panel's actions, such as "Invalidate all queries".
- Drag the top edge to resize the panel. Press the shortcut again, or the close button, to hide it.
- When the panel is closed, a red number on the "k" button counts the errors logged so far.

Keyboard shortcuts:

| Shortcut | What it does |
| --- | --- |
| <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd> | Open or close the panel. The key follows `shortcutKey`. |
| <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> | Open or close the command palette. |
| <kbd>↑</kbd> / <kbd>↓</kbd>, <kbd>Enter</kbd>, <kbd>Esc</kbd> | Move, run and close in the command palette. |

If <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd> clashes with your browser or another tool, pick another key:

```ts
// config/devtools.ts
import { defineConfig } from 'kitr/devtools'

export default defineConfig({
  position: 'bottom-right',
  shortcutKey: 'j',
  maxEntries: 500,
  openByDefault: true,
})
```

## Panels

Three panels are always there. The others appear when their package is installed, because each package's provider contributes its own.

| Panel | Comes from | Shows | Actions |
| --- | --- | --- | --- |
| App | devtools | Mode, environment, boot status and installed packages; every provider with the hooks it implements (`register`, `boot`, `wrap`, `ready`, `shutdown`, `devtools`); every container binding; every config file; public env variables (`VITE_*`, `PUBLIC_*`). | Reload page |
| Router | devtools | The current pathname, search, hash and status; every matched route with its params and loader data; the navigation log. Shows "n/a" without a [router](/packages/router). | Invalidate router (re-run loaders), Navigate to / |
| Log | devtools | Every entry every package logged, newest last, filterable by channel and text. | Clear log |
| Query | [query](/packages/query) | Every cached query with its data and state. | Invalidate all queries, Clear cache |
| Auth | [auth](/packages/auth) | The session and the signed-in user. | Reload session, Refresh token, Sign out |
| Storage | [storage](/packages/storage) | Saved values and cookies. | Clear localStorage, Clear sessionStorage |
| Platform | [platform](/packages/platform) | Platform name, type, OS, whether it is native or standalone, online state, and which driver serves each capability. | |
| Errors | [monitoring](/packages/monitoring) | Every error and message monitoring captured. | Clear errors, Throw a test error |
| Analytics | [analytics](/packages/analytics) | Whether tracking is enabled or queued, the active adapters, and the last 200 calls with their props. | Enable (consent given), Disable, Clear events |

A panel that throws while rendering shows "Panel crashed:" and the error message in its own area. The rest of the overlay and your app keep working.

## Read the log

The Log panel is one timeline for the whole app. Each entry has a time, a channel, a label and optional data you can expand. Pick a channel from the drop-down to see only that package, or type in the filter box to search labels and data.

The channels kitr packages write to:

| Channel | Written by | Example label |
| --- | --- | --- |
| `http` | [http](/packages/http) | `GET /api/orders → 200 (84ms)`; 4xx is a warning, 5xx an error |
| `router` | [router](/packages/router) | `navigated /orders/1042` |
| `query` | [query](/packages/query) | `mutation failed: ["orders","create"]` |
| `auth` | [auth](/packages/auth) | `signed in` |
| `logger` | [logger](/packages/logger) | every log line, at its level |
| `errors`, `breadcrumbs` | [monitoring](/packages/monitoring) | `TypeError: total is undefined` |
| `analytics` | [analytics](/packages/analytics) | `track order.placed` |
| `consent` | [consent](/packages/consent) | `decided` |
| `storage` | [storage](/packages/storage) | `driver: web:local` |
| `platform` | [platform](/packages/platform) | `running as web (macos)` |
| `cache` | [cache](/packages/cache) | `driver: memory` |
| `devtools` | devtools | `ran Clear cache`, or `orders: devtools() failed` |

The `files`, `native`, `notifications`, `offline`, `secure-storage` and `updater` packages log under their own names too.

## Log from your code

To see what your own code does, log to a channel of your own. `getDevtools(app)` returns the hub in development and `null` everywhere else, so the optional call costs nothing in production:

```tsx
// app/features/orders/add-to-cart-button.tsx
import { getDevtools } from 'kitr/devtools'
import { useApp } from 'kitr/react'
import { cart } from './cart'

export function AddToCartButton({ sku }: { sku: string }) {
  const app = useApp()
  return (
    <button
      type="button"
      onClick={() => {
        cart.add(sku, 1)
        getDevtools(app)?.log('orders', `added ${sku}`, { items: cart.items.length })
      }}
    >
      Add to order
    </button>
  )
}
```

Click the button and the Log panel shows a new entry:

```
14:02:31.118  orders  added sku_desk_oak   {1}
```

Expand `{1}` to see `items: 1`. The fourth argument is the level, `'info'` by default:

```ts
// app/features/orders/checkout.ts
import { getDevtools } from 'kitr/devtools'
import type { KitrApp } from 'kitr/app'

export function reportCheckoutProblem(app: KitrApp, orderId: string, reason: string) {
  getDevtools(app)?.log('orders', `checkout blocked for ${orderId}`, { reason }, 'warn')
}
```

Logging is cheap enough to time slow work. Here the checkout logs how long the order request took, as an error when it fails:

```ts
// app/features/orders/place-order.ts
import { getDevtools } from 'kitr/devtools'
import type { KitrApp } from 'kitr/app'

export async function placeOrder(app: KitrApp, orderId: string) {
  const started = performance.now()
  const response = await fetch(`/api/orders/${orderId}/place`, { method: 'POST' })
  const ms = Math.round(performance.now() - started)
  getDevtools(app)?.log(
    'orders',
    `placed ${orderId} in ${ms}ms`,
    { status: response.status },
    response.ok ? 'info' : 'error',
  )
  return response.ok
}
```

| Level | Shown as |
| --- | --- |
| `'debug'` | Grey label. |
| `'info'` | Plain label. The default. |
| `'warn'` | Yellow label. |
| `'error'` | Red label; counted in the Log tab's badge and on the "k" button. |

Don't log with `console.log` and leave it in. Log calls through `getDevtools(app)?.log` are skipped in production without you removing them, and they sit next to the HTTP requests and navigations that caused them.

To check whether devtools is active, for example to skip building a costly debug summary, test the return value once:

```ts
// app/features/orders/debug-summary.ts
import { getDevtools } from 'kitr/devtools'
import type { KitrApp } from 'kitr/app'
import { cart } from './cart'

export function logCartSummary(app: KitrApp) {
  const hub = getDevtools(app)
  if (!hub) return
  const units = cart.items.reduce((sum, item) => sum + item.qty, 0)
  hub.log('orders', `cart has ${cart.items.length} lines, ${units} units`, cart.items, 'debug')
}
```

## Run an action from the command palette

Press <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>. The palette lists "Open" for every panel, then every action of every panel, labelled with its panel. Type to filter, use the arrow keys to pick, and press <kbd>Enter</kbd> to run.

Each run is logged under the `devtools` channel: `ran Clear cache` at the debug level when it works, `Clear cache failed` with the error at the error level when it throws. Actions you add to your own panels appear in the palette automatically.

## Add a panel

A provider contributes panels through a `devtools(app)` method that returns them. Lazy-import the panel module inside it, so the React code never reaches your main bundle:

```ts
// app/providers/orders.ts
import { defineProvider } from 'kitr/app'

export default defineProvider({
  name: 'orders',
  devtools: () => import('./orders-devtools').then((m) => m.panels()),
})
```

Register the provider in `kitrrc.ts`:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'

export default defineKitrConfig({
  // ...
  providers: [
    // ...
    () => import('@kitr/devtools/provider'),
    () => import('#app/providers/orders'),
  ],
})
```

Then write the panel. `definePanel()` gives it types; `KeyValue`, `Badge` and the other parts from `kitr/devtools/ui` match the built-in panels:

```tsx
// app/providers/orders-devtools.tsx
import { definePanel } from 'kitr/devtools'
import { Badge, KeyValue } from 'kitr/devtools/ui'
import { cart } from '#app/features/orders/cart'

export const panels = () => [
  definePanel({
    id: 'orders',
    label: 'Orders',
    badge: () => cart.items.length || null,
    render: () => (
      <div className="kitr-dt-stack">
        <p>
          <Badge tone={cart.items.length ? 'ok' : 'muted'}>{cart.items.length} items</Badge>
        </p>
        <KeyValue rows={cart.items.map((item) => [item.sku, item.qty])} />
      </div>
    ),
    actions: [
      {
        id: 'clear-cart',
        label: 'Empty cart',
        run: (app) => {
          cart.clear()
          app.container.use('devtools').log('orders', 'cart emptied')
        },
      },
    ],
  }),
]
```

Reload the app and an Orders tab appears after the built-in and package panels. The tab's badge shows the item count, and "Empty cart" is a button in the panel and an entry in the command palette. When the provider's `devtools()` method throws, the panel is skipped and the Log shows `orders: devtools() failed` with the error.

What each field does:

| Field | Required | Description |
| --- | --- | --- |
| `id` | yes | Unique id. A panel registered with an existing id replaces it. |
| `label` | yes | The tab text. |
| `render(app)` | yes | Returns the panel body as a React node. Called on every render of the overlay. |
| `badge(app)` | no | Text or a count next to the label. `null`, `undefined`, `0` and `''` show nothing; a badge that throws is hidden. |
| `actions` | no | Buttons under the tabs and entries in the command palette: `{ id, label, run(app) }`. `run` may return a promise. |

The built-in panels have icons in their tabs; panels you add show the label only.

## Refresh a panel when data changes

The overlay re-renders when the hub changes: a new log entry, a panel added or removed, or a call to `notify()`. Data that changes without a log entry, such as the cart above, needs a `notify()`:

```ts
// app/features/orders/cart.ts
export interface CartItem {
  sku: string
  qty: number
}

const listeners = new Set<() => void>()

export const cart = {
  items: [] as CartItem[],
  add(sku: string, qty: number) {
    const line = cart.items.find((item) => item.sku === sku)
    if (line) line.qty += qty
    else cart.items.push({ sku, qty })
    for (const listener of listeners) listener()
  },
  clear() {
    cart.items = []
    for (const listener of listeners) listener()
  },
  subscribe(listener: () => void) {
    listeners.add(listener)
    return () => listeners.delete(listener)
  },
}
```

```ts
// app/providers/orders.ts
import { defineProvider, getDevtools } from 'kitr/app'
import { cart } from '#app/features/orders/cart'

export default defineProvider({
  name: 'orders',
  boot(app) {
    const hub = getDevtools(app)
    if (!hub) return
    cart.subscribe(() => hub.notify())
  },
  devtools: () => import('./orders-devtools').then((m) => m.panels()),
})
```

`notify()` calls in the same tick are merged into one re-render, so a burst of changes does not redraw the panel a dozen times. `getDevtools(app)` is `null` in production, so the subscription only exists in development.

## Build panel bodies

`kitr/devtools/ui` exports the parts the built-in panels use. They are plain React components with no dependencies:

| Component | Props | Renders |
| --- | --- | --- |
| `JsonView` | `value`, `open?`, `depth?` | Any value as an expandable tree. Dates show as ISO strings, errors as `Name: message`. |
| `KeyValue` | `rows: Array<[string, unknown]>` | A two-column table; each value is a `JsonView`. |
| `LogList` | `entries`, `empty?` | Hub entries with time, channel, label and expandable data. |
| `Badge` | `children`, `tone?` | A pill. Tones: `'ok'`, `'warn'`, `'error'`, `'muted'` (default), `'info'`. |
| `Toolbar` | `children` | A row of buttons. |
| `Button` | `children`, `onClick`, `title?` | A small button. |

`styles` is the overlay's stylesheet as a string, already on the page while the overlay is mounted; class names such as `kitr-dt-stack` and `kitr-dt-h` come from it.

A panel that shows the orders log next to the cart:

```tsx
// app/providers/orders-devtools.tsx
import { definePanel } from 'kitr/devtools'
import { JsonView, LogList } from 'kitr/devtools/ui'
import { cart } from '#app/features/orders/cart'

export const panels = () => [
  definePanel({
    id: 'orders',
    label: 'Orders',
    render: (app) => (
      <div className="kitr-dt-stack">
        <section>
          <h4 className="kitr-dt-h">Cart</h4>
          <JsonView value={cart.items} open />
        </section>
        <section>
          <h4 className="kitr-dt-h">Log</h4>
          <LogList entries={app.container.use('devtools').entries('orders')} empty="No cart changes yet" />
        </section>
      </div>
    ),
  }),
]
```

## Read the hub directly

The hub is bound as `devtools` in the container while devtools is active. Besides `log()` and `notify()`, it can read and clear entries and register panels at run time:

```ts
// app/features/orders/debug.ts
import { getDevtools } from 'kitr/devtools'
import type { KitrApp } from 'kitr/app'

export function ordersLog(app: KitrApp) {
  const hub = getDevtools(app)
  if (!hub) return []
  return hub.entries('orders').map((entry) => `${entry.level} ${entry.label}`)
  // => ['info added sku_desk_oak', 'warn checkout blocked for ord_1042']
}
```

| Member | Description |
| --- | --- |
| `log(channel, label, data?, level?)` | Add an entry. Drops the channel's oldest entry past `maxEntries`. |
| `entries(channel?)` | Entries for one channel, or all of them, oldest first. |
| `clear(channel?)` | Remove one channel's entries, or all of them. |
| `register(panel)` | Add a panel now; returns a function that removes it. Providers use `devtools()` instead. |
| `panels` | The registered panels, in tab order. |
| `subscribe(listener)` | Called after changes, once per tick. Returns the unsubscribe function. |
| `notify()` | Ask the overlay to re-render. |

Use `register()` for a panel that only makes sense while a page is open:

```tsx
// app/routes/_app/orders/$orderId.tsx
import { createFileRoute } from '@tanstack/react-router'
import { getDevtools } from 'kitr/devtools'
import { KeyValue } from 'kitr/devtools/ui'
import { useApp } from 'kitr/react'
import { useEffect } from 'react'

export const Route = createFileRoute('/_app/orders/$orderId')({
  component: OrderPage,
})

function OrderPage() {
  const app = useApp()
  const { orderId } = Route.useParams()
  useEffect(() => {
    const hub = getDevtools(app)
    return hub?.register({
      id: 'order-page',
      label: `Order ${orderId}`,
      render: () => <KeyValue rows={[['orderId', orderId]]} />,
    })
  }, [app, orderId])
  return <h1>Order {orderId}</h1>
}
```

The effect returns the function `register()` gave back, so the tab disappears when Ada leaves the page.

## Testing

Devtools is only active in the browser in development, so a test app built with `createTestApp()` has no hub and `getDevtools(app)` returns `null`. Code that logs keeps working in tests and logs nothing. To assert on what your code logs, bind a hub of your own with `createDevtoolsHub()`:

```ts
// app/features/orders/checkout.test.ts
import { createDevtoolsHub, getDevtools } from 'kitr/devtools'
import { createTestApp } from 'kitr/testing'
import { expect, it } from 'vitest'
import { reportCheckoutProblem } from './checkout'

it('logs a blocked checkout as a warning', async () => {
  const app = await createTestApp()
  app.container.value('devtools', createDevtoolsHub({ maxEntries: 50 }))

  reportCheckoutProblem(app, 'ord_1042', 'card declined')

  expect(getDevtools(app)?.entries('orders')).toEqual([
    expect.objectContaining({
      channel: 'orders',
      label: 'checkout blocked for ord_1042',
      data: { reason: 'card declined' },
      level: 'warn',
    }),
  ])
})
```

To check that a provider contributes its panel, boot the real devtools provider in a client app in development mode, and call the panel's action:

```ts
// app/providers/orders.test.ts
import { createApp, getDevtools } from 'kitr/app'
import { devtoolsProvider } from 'kitr/devtools/provider'
import { expect, it } from 'vitest'
import { cart } from '#app/features/orders/cart'
import ordersProvider from './orders'

it('adds the Orders panel and empties the cart', async () => {
  const app = createApp({
    environment: 'client',
    mode: 'development',
    providers: [devtoolsProvider, ordersProvider],
  })
  await app.boot()
  const hub = getDevtools(app)!

  expect(hub.panels.map((p) => p.id)).toEqual(['app', 'router', 'log', 'orders'])

  cart.add('sku_desk_oak', 2)
  const orders = hub.panels.find((p) => p.id === 'orders')!
  expect(orders.badge?.(app)).toBe(1)
  await orders.actions?.find((a) => a.id === 'clear-cart')?.run(app)
  expect(cart.items).toEqual([])
  expect(hub.entries('orders').map((e) => e.label)).toEqual(['cart emptied'])
})
```

Run tests that render the overlay or touch `localStorage` in a DOM environment (`happy-dom` or `jsdom`).

## Extend

Panels follow the `DevtoolsPanel` interface from `kitr/devtools`. A panel is an object, so you can also build one from a function and share it between providers:

```ts
// The interfaces, from kitr/devtools
export interface DevtoolsPanel {
  id: string
  label: string
  badge?: (app: KitrApp) => string | number | null | undefined
  render: (app: KitrApp) => KitrNode
  actions?: DevtoolsAction[]
}

export interface DevtoolsAction {
  id: string
  label: string
  run: (app: KitrApp) => MaybePromise<void>
}
```

This helper turns any log channel into its own panel, with a clear action:

```tsx
// app/devtools/channel-panel.tsx
import { type DevtoolsPanel, definePanel } from 'kitr/devtools'
import { LogList } from 'kitr/devtools/ui'

export function channelPanel(channel: string, label: string): DevtoolsPanel {
  return definePanel({
    id: `channel-${channel}`,
    label,
    badge: (app) => app.container.use('devtools').entries(channel).length || null,
    render: (app) => <LogList entries={app.container.use('devtools').entries(channel)} />,
    actions: [
      {
        id: `clear-${channel}`,
        label: `Clear ${label}`,
        run: (app) => app.container.use('devtools').clear(channel),
      },
    ],
  })
}
```

Return it from any provider's `devtools()` method:

```ts
// app/providers/invoices.ts
import { defineProvider } from 'kitr/app'

export default defineProvider({
  name: 'invoices',
  devtools: () =>
    import('#app/devtools/channel-panel').then((m) => [m.channelPanel('invoices', 'Invoices')]),
})
```

See [`DevtoolsPanel`](/packages/devtools/api#devtoolspanel) and [`DevtoolsHub`](/packages/devtools/api#devtoolshub) in the API reference.

## Next steps

- [API reference](/packages/devtools/api) for every export and type.
- [Configuration](/docs/configuration) for providers and `kitrrc.ts`, where panels are registered.
- [Analytics](/packages/analytics) and [monitoring](/packages/monitoring), whose panels show what would be sent.
- [Logger](/packages/logger), whose output lands in the Log panel.
- [TanStack Router devtools](https://tanstack.com/router/latest/docs/framework/react/devtools) and [TanStack Query devtools](https://tanstack.com/query/latest/docs/framework/react/devtools) for deeper views of each library.


# Files API

Source: https://kitr.dev/packages/files/api

Every export of `kitr/files`, `kitr/files/react`, `kitr/files/provider`, read from the published type definitions. The [guide](/packages/files) shows them in use.

## kitr/files

### acceptFor

```ts
function acceptFor(filters?: FileFilter[]): string;
```

The `accept` string an `<input type="file">` needs for a set of filters.

### createFiles

```ts
function createFiles(config?: FilesConfig, app?: KitrApp): Files;
```

Build the `files` service: the given driver, else the platform's, else the web driver (memory on the server).

### createMemoryFilesDriver

```ts
function createMemoryFilesDriver(queue?: PickedFile[]): FilesDriver & {
  queue: PickedFile[];
  saved: Array<{
    name: string;
    data: FileData;
  }>;
};
```

A driver for tests and the server: `open` returns what you queue, `save` records what was written.

### createWebFilesDriver

```ts
function createWebFilesDriver(): FilesDriver;
```

File System Access API when available, `<input type="file">` and a download link otherwise.

### fromFile

```ts
function fromFile(file: File, path?: string): PickedFile;
```

Wrap a browser `File` (or any Blob with a name) as a `PickedFile`.

### mimeFor

```ts
function mimeFor(name: string, fallback?: string): string;
```

The MIME type for a file name's extension, e.g. `invoice.pdf` → `application/pdf`. Unknown → `fallback`.

### toBlob

```ts
function toBlob(data: FileData, type: string): Blob;
```

Turn any `FileData` into a Blob of the given type. A Blob passes through unchanged.

### useFiles

```ts
function useFiles(app: KitrApp): Files;
```

The `files` service from an app's container, for code outside React.

### defineConfig

```ts
const defineConfig: <const C extends FilesConfig>(config: C) => C;
```

Type-checks `config/files.ts`. Returns the object unchanged.

### FileFilter

```ts
/** A named group of extensions shown in a dialog's file-type menu, e.g. `Invoices (*.pdf)`. */
interface FileFilter {
  /** Shown in the dialog, e.g. `Images`. */
  name: string;
  /** Extensions without the dot, e.g. `['png', 'jpg']`. */
  extensions: string[];
}
```

A named group of extensions shown in a dialog's file-type menu, e.g. `Invoices (*.pdf)`.

### Files

```ts
interface Files {
  /** The driver in use. */
  readonly driver: FilesDriver;
  /** Show the open dialog. Resolves to [] when cancelled. */
  open(options?: OpenOptions): Promise<PickedFile[]>;
  /** Open exactly one file, or null when cancelled. */
  pick(options?: Omit<OpenOptions, 'multiple'>): Promise<PickedFile | null>;
  /** Save data where the person chooses. Resolves to the chosen name or path, or null when cancelled. */
  save(data: FileData, options: SaveOptions): Promise<string | null>;
  /** Open a path with the system's default app. Resolves without doing anything when the driver can't. */
  reveal(path: string): Promise<void>;
}
```

The `files` service bound in the container: open, pick and save through the active driver.

### FilesConfig

```ts
interface FilesConfig {
  /** Use this driver instead of the platform's or the web one. Mostly for tests. */
  driver?: FilesDriver;
  /** Filters added to every dialog, e.g. the app's own document type. */
  filters?: FileFilter[];
}
```

Options for `config/files.ts`.

### FilesDriver

```ts
interface FilesDriver {
  /** Shown in devtools and on `files.driver.name`, e.g. `web` or `memory`. */
  name: string;
  /** Show the open dialog. Resolves to [] when cancelled. */
  open(options: OpenOptions): Promise<PickedFile[]>;
  /** Write data where the person chooses. Resolves to the chosen path/name, or null when cancelled. */
  save(data: FileData, options: SaveOptions): Promise<string | null>;
  /** Open a file with the system's default app, when the platform allows it. */
  reveal?(path: string): Promise<void>;
}
```

The dialogs behind the `files` service. A platform or a test supplies one; the web driver is the fallback.

### OpenOptions

```ts
interface OpenOptions {
  /** File types to offer. Merged with the `filters` in `config/files.ts`. */
  filters?: FileFilter[];
  /** Let the person choose more than one file. Default false. */
  multiple?: boolean;
  /** Dialog title where the platform shows one. */
  title?: string;
}
```

Options for `open()` and `pick()`.

### PickedFile

```ts
interface PickedFile {
  /** File name with extension, without a directory. */
  name: string;
  /** Size in bytes. */
  size: number;
  /** MIME type, or `''` when the platform doesn't know it. */
  type: string;
  /** Absolute path on platforms that expose one (desktop, mobile). */
  path?: string;
  /** Read the content as UTF-8 text. */
  text(): Promise<string>;
  /** Read the content as bytes. */
  bytes(): Promise<Uint8Array>;
  /** Read the content as a Blob, e.g. to upload it. */
  blob(): Promise<Blob>;
}
```

A file the person chose, the same shape on every platform. Its content is read on demand.

### SaveOptions

```ts
interface SaveOptions {
  /** Suggested file name, with extension. */
  name: string;
  /** File types to offer. Merged with the `filters` in `config/files.ts`. */
  filters?: FileFilter[];
  /** Dialog title where the platform shows one. */
  title?: string;
  /** MIME type for the download fallback. Default from the extension or `application/octet-stream`. */
  type?: string;
}
```

Options for `save()`: the suggested name and, for the download fallback, the MIME type.

### FileData

```ts
type FileData = string | Blob | Uint8Array | ArrayBuffer;
```

What `save()` accepts: text, a Blob or File, or raw bytes.

## kitr/files/react

### useDropFiles

```ts
function useDropFiles(onFiles: (files: PickedFile[]) => void): {
  over: boolean;
  onDragOver: (e: {
    preventDefault(): void;
  }) => void;
  onDragLeave: () => void;
  onDrop: (e: {
    preventDefault(): void;
    dataTransfer: DataTransfer | null;
  }) => Promise<void>;
};
```

Drag-and-drop handlers that hand dropped files over as `PickedFile`s.

### useFileDialogs

```ts
function useFileDialogs(): {
  busy: boolean;
  open: (options?: OpenOptions | undefined) => Promise<PickedFile[]>;
  pick: (options?: Omit<OpenOptions, "multiple"> | undefined) => Promise<PickedFile | null>;
  save: (data: FileData, options: SaveOptions) => Promise<string | null>;
};
```

`const { open, save, busy } = useFileDialogs()`: the service with a busy flag while a dialog is up.

### useFiles

```ts
function useFiles(): Files;
```

The `files` service from the app in context. Use `useFileDialogs()` when you want a busy flag.

## kitr/files/provider

### filesProvider

```ts
const filesProvider: import("@kitr/core").KitrProvider;
```

Binds `files` to the native dialog driver a platform package registered (`files` capability),
or the web driver. Nothing runs on the server beyond a no-op binding.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Files

Source: https://kitr.dev/packages/files

Sooner or later someone wants to get a file in or out of your app: import last month's orders from a spreadsheet, export invoices as CSV, attach a receipt. `kitr/files` gives you one service with three calls, `open()`, `pick()` and `save()`, that shows the best dialog the current platform has. Components call the same API everywhere and never check which browser or shell they run in.

In Chrome and Edge it uses the [File System Access API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API), so saving writes to the exact file the person chose. Everywhere else it falls back to a hidden `<input type="file">` to open and a download link to save. A platform or your own code can register a native driver that adds real file paths. Every picked file has the same shape, a `PickedFile`, with `text()`, `bytes()` and `blob()`.

It runs in the browser and in desktop and mobile shells. On the server the service exists but has no dialogs. To receive files on your server and store them, use [Uploads](/packages/uploads); `kitr/files` only gets them into and out of the browser.

This guide follows Acme's billing screen at `app.acme.com`: Ada imports orders from a CSV, attaches receipts to an invoice, and exports invoices for Grace in accounting.

## When to use it

Use `kitr/files` when **the person's own device** is the source or destination: they choose a file to open, or choose where a file you generated is saved. The content stays in the browser until your code sends it somewhere.

Use [Uploads](/packages/uploads) when the file must **reach your server or object storage**: progress bars, size limits, presigned URLs and virus scanning are its job. The two work together: pick with `kitr/files`, then hand the `Blob` to an upload.

## Install

```sh
kitr add files
```

What `kitr add` does:

- Adds [Platform](/packages/platform) first, when the project doesn't have it, because `files` requires it.
- Installs `@kitr/files`.
- Adds `() => import('@kitr/files/provider')` to `providers` in `kitrrc.ts`.
- Adds `@kitr/files` to `packages` in `kitrrc.ts`.
- Writes `config/files.ts` (shown under [Configure](#configure)).
- Adds a `## kitr: files` section to `AGENTS.md`: open, pick and save with `useFileDialogs()` from `kitr/files/react` or `app.container.use('files')`, never build `<input type="file">` or download links by hand, and expect a cancelled dialog to resolve to `[]` or `null`.

`kitr add files` asks no questions and adds no environment variables or scripts. It is a client package, so in a server-only project it prints `files is a client package; this project is server-only. Skipping.` and changes nothing. No kit includes it.

`kitr remove files` reverses every step above and deletes `config/files.ts`, then lists the files that still import `kitr/files`. It leaves Platform installed.

## Configure

`kitr add files` writes this file:

```ts
// config/files.ts
import { defineConfig } from 'kitr/files'

export default defineConfig({
  // Filters added to every open/save dialog.
  filters: [],
})
```

| Option | Default | Description |
| --- | --- | --- |
| `filters` | `[]` | File types added to every dialog, after the ones a call passes. Use it for your app's own document type. |
| `filters[].name` | | The label in the dialog's file-type menu, such as `Acme projects`. |
| `filters[].extensions` | | Extensions without the dot, such as `['acme']`. Case, leading dots and spaces are ignored; `'*'` and empty strings are dropped. |
| `driver` | the platform's driver, else the web driver | Replace the dialogs. Tests pass `createMemoryFilesDriver()` here. |

`kitr/files` adds no environment variables.

The provider binds one `files` service in the container. It picks its driver the first time the service is used: `driver` from config if set, then a driver a platform registered under the `files` capability, then the web driver in a browser, and an in-memory driver on the server.

Acme's app has its own project export format, so every dialog offers it:

```ts
// config/files.ts
import { defineConfig } from 'kitr/files'

export default defineConfig({
  filters: [{ name: 'Acme projects', extensions: ['acme'] }],
})
```

## Save your first file

Export Acme's open orders as a CSV with one button. `useFileDialogs()` returns the service's calls plus a `busy` flag:

```tsx
// app/features/orders/export-orders-button.tsx
import { useFileDialogs } from 'kitr/files/react'

const orders = [
  { id: 'ord_1042', customer: 'Ada', total: 129 },
  { id: 'ord_1043', customer: 'Grace', total: 80 },
]

export function ExportOrdersButton() {
  const { save, busy } = useFileDialogs()

  async function exportOrders() {
    const csv = ['id,customer,total', ...orders.map((o) => `${o.id},${o.customer},${o.total}`)].join('\n')
    const where = await save(csv, { name: 'acme-orders.csv' })
    if (where) console.log(`Saved to ${where}`)
  }

  return (
    <button type="button" disabled={busy} onClick={exportOrders}>
      Export orders
    </button>
  )
}
```

Click **Export orders**. In Chrome or Edge a save dialog opens with `acme-orders.csv` filled in; choose a folder and the console prints `Saved to acme-orders.csv`, the name the person kept. In Firefox and Safari the browser downloads `acme-orders.csv` right away. The file holds:

```text
id,customer,total
ord_1042,Ada,129
ord_1043,Grace,80
```

`save()` resolves to the saved name, a path on platforms that have one, or `null` when the person cancels. Call it from a click handler: browsers only show file dialogs in response to a user gesture.

## Open a file and read it

`pick()` opens a dialog for exactly one file and resolves to a `PickedFile`, or `null` when the person cancels. Read its content with `text()`:

```tsx
// app/features/orders/import-orders-button.tsx
import { useFileDialogs } from 'kitr/files/react'
import { useState } from 'react'

interface ImportedOrder {
  id: string
  customer: string
  total: number
}

function parseOrders(csv: string): ImportedOrder[] {
  const [, ...rows] = csv.trim().split('\n')
  return rows.map((row) => {
    const [id = '', customer = '', total = '0'] = row.split(',')
    return { id, customer, total: Number(total) }
  })
}

export function ImportOrdersButton() {
  const { pick, busy } = useFileDialogs()
  const [imported, setImported] = useState<ImportedOrder[]>([])

  async function importOrders() {
    const file = await pick({ filters: [{ name: 'Spreadsheets', extensions: ['csv'] }] })
    if (!file) return
    setImported(parseOrders(await file.text()))
  }

  return (
    <div>
      <button type="button" disabled={busy} onClick={importOrders}>
        Import orders
      </button>
      <p>{imported.length} orders imported</p>
    </div>
  )
}
```

Choose the `acme-orders.csv` you exported and the paragraph reads `2 orders imported`. Nothing has left the browser; send the rows to your API with a [mutation](/packages/query) when the person confirms.

## Open several files

`open()` resolves to an array. Pass `multiple: true` to let the person select more than one file. Without it, `open()` still returns an array, with at most one entry:

```tsx
// app/features/invoices/attach-receipts.tsx
import type { PickedFile } from 'kitr/files'
import { useFileDialogs } from 'kitr/files/react'
import { useState } from 'react'

export function AttachReceipts({ invoiceId }: { invoiceId: string }) {
  const { open, busy } = useFileDialogs()
  const [receipts, setReceipts] = useState<PickedFile[]>([])

  async function attach() {
    const files = await open({
      multiple: true,
      title: `Receipts for ${invoiceId}`,
      filters: [
        { name: 'Images', extensions: ['png', 'jpg', 'jpeg'] },
        { name: 'PDF', extensions: ['pdf'] },
      ],
    })
    setReceipts((current) => [...current, ...files])
  }

  return (
    <div>
      <button type="button" disabled={busy} onClick={attach}>
        Attach receipts
      </button>
      <ul>
        {receipts.map((file) => (
          <li key={file.name}>
            {file.name} ({Math.round(file.size / 1024)} KB)
          </li>
        ))}
      </ul>
    </div>
  )
}
```

Ada selects `taxi.jpg` and `hotel.pdf`; the list shows both with their sizes. A cancelled dialog resolves to `[]`, so the list stays as it was. `title` is shown by platform drivers that have a titled dialog; browsers ignore it.

## Filter by file type

`filters` decides which files the dialog offers. Each filter is a label and a list of extensions. The filters you pass come first, then the ones in `config/files.ts`:

```ts
// app/features/projects/open-project.ts
import { useFiles } from 'kitr/files'
import { app } from '#app/app'

// With `filters: [{ name: 'Acme projects', extensions: ['acme'] }]` in config,
// the dialog offers "JSON" first and "Acme projects" second.
export function openProject() {
  return useFiles(app).pick({ filters: [{ name: 'JSON', extensions: ['json'] }] })
}
```

Extensions are cleaned before they reach the dialog: `'.PNG'`, `'png'` and `' png '` are the same, duplicates are merged, and `'*'` or `''` is dropped. A filter left with no extensions is not shown in the File System Access picker. `acceptFor()` turns filters into the `accept` string a file input needs, which is what the fallback uses:

```ts
import { acceptFor } from 'kitr/files'

acceptFor([
  { name: 'Images', extensions: ['.PNG', 'jpg', '*'] },
  { name: 'PDF', extensions: ['pdf'] },
])
// => '.png,.jpg,.pdf'
```

Filters are a convenience, not a check. Most dialogs let the person switch to "All files", and the file input fallback lists every filter as one combined list. Check `file.name` or `file.type` before you trust the content:

```ts
// app/features/orders/check-file.ts
import type { PickedFile } from 'kitr/files'

export function assertCsv(file: PickedFile) {
  if (!file.name.toLowerCase().endsWith('.csv')) throw new Error(`${file.name} is not a CSV file`)
}
```

## Read a file's content

A `PickedFile` holds the file's details and reads its content only when you ask:

| Member | Type | Description |
| --- | --- | --- |
| `name` | `string` | File name with extension, such as `taxi.jpg`. |
| `size` | `number` | Size in bytes. |
| `type` | `string` | The MIME type the platform reports, such as `image/jpeg`. Can be `''`. |
| `path` | `string \| undefined` | Absolute path, only on drivers that have one. Always `undefined` in a browser. |
| `text()` | `Promise<string>` | The content as UTF-8 text. |
| `bytes()` | `Promise<Uint8Array>` | The content as bytes. |
| `blob()` | `Promise<Blob>` | The content as a `Blob`. In a browser this is the original `File`. |

Use `text()` for CSV, JSON and Markdown, `bytes()` when you parse a binary format yourself, and `blob()` to preview or send a file:

```tsx
// app/features/invoices/receipt-preview.tsx
import type { PickedFile } from 'kitr/files'
import { useEffect, useState } from 'react'

export function ReceiptPreview({ file }: { file: PickedFile }) {
  const [url, setUrl] = useState<string>()

  useEffect(() => {
    let objectUrl: string | undefined
    file.blob().then((blob) => {
      objectUrl = URL.createObjectURL(blob)
      setUrl(objectUrl)
    })
    return () => {
      if (objectUrl) URL.revokeObjectURL(objectUrl)
    }
  }, [file])

  if (!url) return null
  return file.type === 'application/pdf' ? (
    <iframe src={url} title={file.name} />
  ) : (
    <img src={url} alt={file.name} />
  )
}
```

Reading a large file into memory is slow. Check `file.size` first and refuse anything your feature can't handle, before calling `text()` or `bytes()`.

To turn a browser `File` from somewhere else, such as a paste event, into the same shape, call `fromFile(file)`. The optional second argument sets `path`.

## Save text, bytes and blobs

`save(data, options)` accepts a string, a `Blob` or `File`, a `Uint8Array` or an `ArrayBuffer`. `name` is required and suggests the file name. In the download fallback, `type` sets the MIME type; without it the type comes from the extension:

```ts
// app/features/invoices/export.ts
import { useFiles } from 'kitr/files'
import { app } from '#app/app'

// Text: the type is text/csv, from the extension.
export function exportInvoiceCsv() {
  return useFiles(app).save('id,total\nINV-1042,129', { name: 'invoices-2024-11.csv' })
}

// JSON for the app's own format, with the type set explicitly.
export function exportProject() {
  const project = { id: 'prj_7', name: 'Website relaunch', team: 'Design' }
  return useFiles(app).save(JSON.stringify(project, null, 2), {
    name: 'website-relaunch.acme',
    type: 'application/json',
    filters: [{ name: 'Acme projects', extensions: ['acme'] }],
  })
}

// Bytes from an API that renders PDFs.
export async function downloadInvoicePdf() {
  const response = await fetch('https://api.acme.com/invoices/INV-1042.pdf')
  return useFiles(app).save(await response.blob(), { name: 'INV-1042.pdf' })
}
```

`mimeFor(name)` is the lookup `save()` uses. It knows `txt`, `md`, `csv`, `json`, `html`, `png`, `jpg`, `jpeg`, `gif`, `svg`, `pdf` and `zip`, and returns `application/octet-stream` (or the fallback you pass) for anything else:

```ts
import { mimeFor, toBlob } from 'kitr/files'

mimeFor('INV-1042.PDF') // => 'application/pdf'
mimeFor('website-relaunch.acme') // => 'application/octet-stream'
mimeFor('website-relaunch.acme', 'application/json') // => 'application/json'

toBlob('id,total', 'text/csv').type // => 'text/csv'
```

`toBlob(data, type)` is the other helper: it turns any `FileData` into a `Blob`, and returns a `Blob` you pass unchanged.

## Know when the person cancelled

Cancelling a dialog is not an error. `open()` resolves to `[]`, `pick()` to `null` and `save()` to `null`, so a cancel needs no `try`/`catch`:

```ts
// app/features/orders/import.ts
import { useFiles } from 'kitr/files'
import { app } from '#app/app'

export async function importOrdersFile() {
  const file = await useFiles(app).pick({ filters: [{ name: 'Spreadsheets', extensions: ['csv'] }] })
  if (file === null) return null // Ada closed the dialog. Leave the screen as it was.
  return file.text()
}
```

With the download fallback, `save()` resolves to `name` as soon as the download starts, because the browser doesn't tell the page whether the person kept the file. Don't show "Saved" as a fact in that case; "Download started" is honest.

With the file input fallback, the dialog resolves `[]` on cancel only in browsers that fire the input's `cancel` event. In older browsers a cancelled dialog never resolves, and `busy` from `useFileDialogs()` stays `true` until the next dialog completes.

## Show a busy state while a dialog is open

`useFileDialogs()` wraps `open`, `pick` and `save` so `busy` is `true` from the moment a call starts until it settles, including the time the dialog is on screen and the time it takes to write the file:

```tsx
// app/features/invoices/export-invoices.tsx
import { useFileDialogs } from 'kitr/files/react'

export function ExportInvoices({ csv }: { csv: string }) {
  const { save, busy } = useFileDialogs()
  return (
    <button type="button" disabled={busy} onClick={() => save(csv, { name: 'acme-invoices.csv' })}>
      {busy ? 'Exporting…' : 'Export invoices'}
    </button>
  )
}
```

Disabling the button while `busy` stops a double click from opening two dialogs. If you don't need the flag, `useFiles()` from `kitr/files/react` returns the service itself, including `reveal()` and `driver`.

## Accept dropped files

`useDropFiles(onFiles)` returns drag-and-drop handlers that hand dropped files to your callback as `PickedFile`s, plus an `over` flag for styling the drop zone:

```tsx
// app/features/invoices/receipt-drop-zone.tsx
import type { PickedFile } from 'kitr/files'
import { useDropFiles } from 'kitr/files/react'

export function ReceiptDropZone({ onReceipts }: { onReceipts: (files: PickedFile[]) => void }) {
  const { over, ...handlers } = useDropFiles(onReceipts)
  return (
    <div {...handlers} className={over ? 'border-2 border-blue-500' : 'border-2 border-dashed'}>
      Drop receipts here
    </div>
  )
}
```

Spread only the handlers (`onDragOver`, `onDragLeave` and `onDrop`) onto the element. Don't spread the whole return value: React would put `over` on the `<div>` as an unknown attribute and warn. `onDrop` prevents the browser from opening the file in the tab. Dropped files go through no filters, so check them the same way as picked ones.

## Use files outside React

Outside components, get the service from the app's container. `useFiles(app)` from `kitr/files` is a shortcut for `app.container.use('files')`:

```ts
// app/features/projects/project-files.ts
import { useFiles } from 'kitr/files'
import { app } from '#app/app'

export interface Project {
  id: string
  name: string
  team: string
}

export async function exportProject(project: Project) {
  const files = useFiles(app)
  return files.save(JSON.stringify(project, null, 2), { name: `${project.id}.acme` })
}

export async function importProject(): Promise<Project | null> {
  const file = await useFiles(app).pick()
  return file ? (JSON.parse(await file.text()) as Project) : null
}
```

`importProject()` offers the `Acme projects` filter from config, because config filters apply to every call. `files.driver.name` tells you which driver is active: `web`, `memory`, or the name a platform driver gives itself.

## Open a saved file in its app

`reveal(path)` asks the driver to open a file with the system's default app, such as opening the exported PDF in a viewer. Only drivers that know real paths can do it, so check that the driver has `reveal` first:

```ts
// app/features/invoices/open-invoice.ts
import { useFiles } from 'kitr/files'
import { app } from '#app/app'

export async function saveAndOpenInvoice() {
  const files = useFiles(app)
  const pdf = await (await fetch('/api/invoices/INV-1042.pdf')).blob()
  const where = await files.save(pdf, { name: 'INV-1042.pdf' })
  if (where && files.driver.reveal) await files.reveal(where)
}
```

The web and memory drivers have no `reveal`; the call resolves and does nothing. `useFileDialogs()` doesn't return `reveal`; use `useFiles()` in components.

## Send a picked file to your server

A `PickedFile` gives you a `Blob`, which `fetch` and `FormData` accept directly. For a small file and your own endpoint, that's enough:

```ts
// app/features/invoices/upload-receipt.ts
import type { PickedFile } from 'kitr/files'

export async function uploadReceipt(invoiceId: string, file: PickedFile) {
  const body = new FormData()
  body.append('receipt', await file.blob(), file.name)
  const response = await fetch(`/api/invoices/${invoiceId}/receipts`, { method: 'POST', body })
  if (!response.ok) throw new Error(`Upload failed with ${response.status}`)
  return (await response.json()) as { id: string; url: string }
}
```

For progress, size limits, retries or direct uploads to object storage, pass the blob to [Uploads](/packages/uploads) instead.

## Where it runs

The service picks a driver once, the first time it is used. The table shows what each environment gets today:

| Where the app runs | Driver | Open | Save | `path` |
| --- | --- | --- | --- | --- |
| Chrome, Edge and other Chromium browsers | `web` | File System Access picker | Save picker, writes the chosen file | no |
| Firefox, Safari | `web` | Hidden `<input type="file">` | Download link | no |
| Desktop shell (Electron or Tauri) | `web`, unless you register one | The shell's webview decides | The shell's webview decides | no |
| Mobile shell (Capacitor) | `web`, unless you register one | The system picker behind `<input type="file">` | Download link | no |
| Server | `memory` | Resolves `[]` | Records the call, resolves `name` | no |

### Chrome and Edge

The web driver calls `showOpenFilePicker` and `showSaveFilePicker`. The save picker writes the bytes into the file the person chose and resolves to its name. See [MDN on `showSaveFilePicker`](https://developer.mozilla.org/en-US/docs/Web/API/Window/showSaveFilePicker) for support and limits. The API needs a secure context: `https://` or `http://localhost`.

### Firefox and Safari

The web driver adds a hidden `<input type="file">` to the page, sets its `accept` from your filters, clicks it and removes it once the person chooses or cancels. To save, it creates an object URL, clicks a hidden `<a download>` and revokes the URL a second later. The browser decides where the download goes.

### Desktop

[Desktop](/packages/desktop) doesn't register a `files` driver today, so the web driver runs inside the shell's webview. Electron, the recommended shell, embeds Chromium, so the File System Access pickers show the OS dialogs, but picked files have no `path` and `reveal()` does nothing. For real paths, write a driver over your IPC contract, as [Extend](#extend) shows for Electron.

### Mobile

[Mobile](/packages/mobile) doesn't register a `files` driver today either. Inside Capacitor, the file input opens the system picker. Downloads from a WebView depend on the shell, so test saving on a device, or register a driver that uses a Capacitor filesystem or share plugin.

## Errors

Cancelling is never an error. Anything else the dialog throws reaches your code as it was thrown:

| Error | When | What to do |
| --- | --- | --- |
| `AbortError` | The person cancelled the File System Access picker. | Nothing: `kitr/files` catches it and resolves `[]` or `null`. |
| `SecurityError` | The picker was called without a user gesture, such as from a timer or after an `await` that took too long. | Call `open`, `pick` or `save` directly from a click or key handler. |
| `NotAllowedError` | The browser or the person denied write access to the chosen file. | Show a message and offer to save again. |
| `TypeError` | The picker rejected its options, such as a filter it can't read. | Check your `filters`. |

```ts
// app/features/invoices/export-safely.ts
import { useFiles } from 'kitr/files'
import { app } from '#app/app'

export async function exportInvoices(csv: string) {
  try {
    return await useFiles(app).save(csv, { name: 'acme-invoices.csv' })
  } catch (error) {
    if (error instanceof Error && error.name === 'SecurityError') {
      throw new Error('Click Export again to choose where to save.')
    }
    throw error
  }
}
```

## Testing

Pass `createMemoryFilesDriver(queue)` as the `driver` in config. `open()` and `pick()` take files from the front of `queue` instead of showing a dialog, and `save()` records each call in `driver.saved` and resolves to `name`. An empty queue behaves like a cancelled dialog.

```ts
// app/features/orders/files.test.ts
import { createMemoryFilesDriver, fromFile, useFiles } from 'kitr/files'
import filesProvider from 'kitr/files/provider'
import { createTestApp } from 'kitr/testing'
import { describe, expect, it } from 'vitest'

describe('order files', () => {
  it('imports a picked CSV and exports invoices', async () => {
    const csv = new File(['id,customer,total\nord_1042,Ada,129'], 'acme-orders.csv', {
      type: 'text/csv',
    })
    const driver = createMemoryFilesDriver([fromFile(csv)])
    const app = await createTestApp({
      providers: [filesProvider],
      config: { files: { driver, filters: [{ name: 'Acme projects', extensions: ['acme'] }] } },
    })
    const files = useFiles(app)

    const picked = await files.pick({ filters: [{ name: 'Spreadsheets', extensions: ['csv'] }] })
    expect(picked?.name).toBe('acme-orders.csv')
    expect(await picked?.text()).toContain('ord_1042,Ada,129')

    expect(await files.pick()).toBeNull()

    expect(await files.save('id,total\nINV-1042,129', { name: 'acme-invoices.csv' })).toBe(
      'acme-invoices.csv',
    )
    expect(driver.saved).toEqual([{ name: 'acme-invoices.csv', data: 'id,total\nINV-1042,129' }])
  })
})
```

`open({ multiple: true })` takes every queued file at once; without `multiple`, each call takes one. Push more files with `driver.queue.push(...)` between calls.

To test a component, render it inside the same app with `renderWithKitr` from `kitr/testing/react` in a DOM environment, click the button, and read `driver.saved`:

```tsx
// app/features/orders/export-orders-button.test.tsx
// @vitest-environment happy-dom
import { fireEvent, screen, waitFor } from '@testing-library/react'
import { createMemoryFilesDriver } from 'kitr/files'
import filesProvider from 'kitr/files/provider'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { expect, it } from 'vitest'
import { ExportOrdersButton } from './export-orders-button'

it('exports the orders as CSV', async () => {
  const driver = createMemoryFilesDriver()
  const app = await createTestApp({ providers: [filesProvider], config: { files: { driver } } })
  renderWithKitr(<ExportOrdersButton />, { app })

  fireEvent.click(screen.getByRole('button', { name: 'Export orders' }))

  await waitFor(() => expect(driver.saved).toHaveLength(1))
  expect(driver.saved[0]?.name).toBe('acme-orders.csv')
  expect(driver.saved[0]?.data).toBe('id,customer,total\nord_1042,Ada,129\nord_1043,Grace,80')
})
```

## Extend

A driver supplies the dialogs. Write one when a platform has better ones than the browser, for example to get real paths on desktop. The interface is `FilesDriver` in the [API reference](/packages/files/api):

| Member | Description |
| --- | --- |
| `name` | Shown in devtools and on `files.driver.name`. |
| `open(options)` | Show the open dialog with `filters`, `multiple` and `title`. Resolve to the picked files, or `[]` when cancelled. |
| `save(data, options)` | Write `data` where the person chooses, starting from `options.name`. Resolve to the path or name, or `null` when cancelled. |
| `reveal(path)` | Optional. Open a path with the system's default app. |

`options.filters` already includes the config filters when the service calls your driver.

### An Electron driver

This driver uses Electron's [`dialog`](https://www.electronjs.org/docs/latest/api/dialog) in the main process through [Desktop](/packages/desktop)'s typed IPC. First add three commands to the IPC contract:

```ts
// platforms/app/ipc.ts
import type { FileFilter } from 'kitr/files'

export type Ipc = {
  'app.version': () => string
  'files.open': (options: { filters?: FileFilter[]; multiple?: boolean; title?: string }) => Array<{
    path: string
    bytes: Uint8Array
  }>
  'files.save': (data: string | Uint8Array, options: { name: string; filters?: FileFilter[]; title?: string }) => string | null
  'files.reveal': (path: string) => void
}
```

Then implement them in the main process:

```ts
// platforms/app/main.ts
import { readFile, writeFile } from 'node:fs/promises'
import { app, dialog, ipcMain, shell } from 'electron'
import { handleIpc, handleKitrIpc } from 'kitr/desktop/electron-main'
import type { Ipc } from './ipc'

handleIpc<Ipc>(ipcMain, {
  'app.version': () => app.getVersion(),
  'files.open': async (_event, options) => {
    const result = await dialog.showOpenDialog({
      title: options.title,
      filters: options.filters,
      properties: options.multiple ? ['openFile', 'multiSelections'] : ['openFile'],
    })
    if (result.canceled) return []
    return Promise.all(result.filePaths.map(async (path) => ({ path, bytes: await readFile(path) })))
  },
  'files.save': async (_event, data, options) => {
    const result = await dialog.showSaveDialog({
      title: options.title,
      defaultPath: options.name,
      filters: options.filters,
    })
    if (result.canceled || !result.filePath) return null
    await writeFile(result.filePath, data)
    return result.filePath
  },
  'files.reveal': async (_event, path) => {
    await shell.openPath(path)
  },
})

app.whenReady().then(() => {
  handleKitrIpc(ipcMain, app)
  // ... create the window
})
```

In the renderer, turn the IPC calls into a `FilesDriver` and register it under the `files` capability from a provider:

```ts
// app/providers/electron-files.ts
import { defineProvider } from 'kitr/app'
import { createIpcClient } from 'kitr/desktop/electron'
import { type FileData, type FilesDriver, mimeFor, type PickedFile, toBlob } from 'kitr/files'
import type { Ipc } from '../../platforms/app/ipc'

const ipc = createIpcClient<Ipc>()

function picked(path: string, bytes: Uint8Array): PickedFile {
  const name = path.split(/[\\/]/).pop() ?? path
  const type = mimeFor(name, '')
  return {
    name,
    path,
    size: bytes.byteLength,
    type,
    text: async () => new TextDecoder().decode(bytes),
    bytes: async () => bytes,
    blob: async () => toBlob(bytes, type),
  }
}

async function toSendable(data: FileData): Promise<string | Uint8Array> {
  if (typeof data === 'string' || data instanceof Uint8Array) return data
  if (data instanceof Blob) return new Uint8Array(await data.arrayBuffer())
  return new Uint8Array(data)
}

export const electronFilesDriver: FilesDriver = {
  name: 'electron',
  async open(options) {
    const files = await ipc.invoke('files.open', options)
    return files.map((f) => picked(f.path, f.bytes))
  },
  async save(data, options) {
    return ipc.invoke('files.save', await toSendable(data), options)
  },
  reveal: (path) => ipc.invoke('files.reveal', path),
}

export default defineProvider({
  name: 'electron-files',
  register(app) {
    if (ipc.available) app.drivers.register('files', electronFilesDriver, { platform: 'desktop' })
  },
})
```

Add `() => import('#app/providers/electron-files')` to `providers` in `kitrrc.ts`. The files service resolves its driver on first use, after every provider has registered, so the order in the list doesn't matter. In a plain browser `ipc.available` is `false`, nothing is registered, and the web driver runs as before. Picked files now have a `path`, and `reveal(path)` opens them in the default app.

The same shape works for any shell: [Tauri's dialog plugin](https://v2.tauri.app/plugin/dialog/) with its fs plugin, or a Capacitor file picker plugin on mobile.

## Devtools

`kitr/files` has no panel. With [Devtools](/packages/devtools) installed, the service writes to the Log panel under `files`: `open` with the names of the chosen files, and `save` with the name or path it saved to (`null` on cancel). `pick()` doesn't log.

## Next steps

- [API reference](/packages/files/api)
- [Uploads](/packages/uploads): send picked files to your server or object storage.
- [Platform](/packages/platform): where the app runs, and the drivers platforms register.
- [Desktop](/packages/desktop): the Electron shell and its typed IPC.
- [MDN: File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API)


# Feature flags API

Source: https://kitr.dev/packages/flags/api

Every export of `kitr/flags`, `kitr/flags/react`, `kitr/flags/provider`, `kitr/flags/server`, read from the published type definitions. The [guide](/packages/flags) shows them in use.

## kitr/flags

### createFlags

```ts
function createFlags<D extends FlagDefinitions>(definitions: D, config?: FlagsConfig, app?: KitrApp, options?: CreateFlagsOptions): Flags<D>;
```

Build a flags service from definitions and a config: what the provider binds, and what tests call directly.

### defineFlags

```ts
function defineFlags<const D extends FlagDefinitions>(definitions: D): D;
```

Declare every flag once, in `app/flags.ts`, with its default and a sentence on what it gates.

### envFlagsProvider

```ts
function envFlagsProvider(env?: Record<string, string | undefined>, prefix?: string): FlagsProvider;
```

Answer from environment variables: `FLAG_NEW_DASHBOARD=true` answers `newDashboard` and `new-dashboard`. Reads `process.env` unless given a map.

### openFeatureFlagsProvider

```ts
function openFeatureFlagsProvider(client: {
  getBooleanValue(key: string, def: boolean, ctx?: any): boolean | Promise<boolean>;
  getStringValue(key: string, def: string, ctx?: any): string | Promise<string>;
  getNumberValue(key: string, def: number, ctx?: any): number | Promise<number>;
}, definitions: FlagDefinitions): FlagsProvider;
```

An OpenFeature client (`@openfeature/web-sdk` or `server-sdk`) as a kitr provider; the typed
defaults in `app/flags.ts` pick which `get*Value` to call.

### percentageFlagsProvider

```ts
function percentageFlagsProvider(shares: Record<string, number>, salt?: string): FlagsProvider;
```

Turn a flag on for a share of users, stable per user id. `percentageFlagsProvider({ beta: 10 })`.

### readEmbeddedFlags

```ts
function readEmbeddedFlags(): FlagMap | undefined;
```

Read the snapshot a server page embedded, if any. `undefined` on the server, without the tag, or when its JSON is broken.

### staticFlagsProvider

```ts
function staticFlagsProvider(values: Partial<FlagMap> | ((context: FlagContext) => Partial<FlagMap>)): FlagsProvider;
```

A fixed map, or a function of the context: `{ newDashboard: true }` or `(ctx) => ...`.

### useFlags

```ts
function useFlags<D extends FlagDefinitions = FlagDefinitions>(app: KitrApp): Flags<D>;
```

The app's flags service, from the container, outside React.

### defineConfig

```ts
const defineConfig: <const C extends FlagsConfig>(config: C) => C;
```

Type the default export of `config/flags.ts`. Returns its argument unchanged.

### FLAGS_SCRIPT_ID

```ts
const FLAGS_SCRIPT_ID = "__kitr_flags__";
```

The id of the JSON script tag that carries the server's snapshot to the browser.

### CreateFlagsOptions

```ts
interface CreateFlagsOptions {
  /**
   * Whether `resolve()` updates the snapshot that `value()`, `isEnabled()` and the React hooks
   * read. Default: everywhere but the server's root app, which serves every user at once (the
   * provider binds one instance per request there, and those keep their snapshot).
   */
  keepSnapshot?: boolean;
}
```

Options for `createFlags()` beyond the config.

### FlagContext

```ts
interface FlagContext {
  /** Stable id of the user; percentage rollouts and OpenFeature's `targetingKey` use it. */
  userId?: string;
  [key: string]: unknown;
}
```

Who is asking: the user, their plan, the request. Providers target on it.

### FlagDefinition

```ts
interface FlagDefinition<T extends FlagValue = FlagValue> {
  /** The value when no provider answers. */
  default: T;
  /** A sentence on what the flag gates, for the people who flip it. */
  description?: string;
}
```

One flag in `defineFlags()`: its default, whose type fixes the flag's type, and what it gates.

### Flags

```ts
interface Flags<D extends FlagDefinitions = FlagDefinitions> {
  /** The current answer. Synchronous: works from a resolved snapshot (and the defaults before one). */
  value<K extends keyof D & string>(key: K): D[K]['default'];
  /** True only when the flag's current value is exactly `true`. */
  isEnabled(key: keyof D & string): boolean;
  /** Every flag, resolved for `context`. Server: once per request. Client: once per session, then cached. */
  resolve(context?: FlagContext): Promise<FlagValues<D>>;
  /** Load a snapshot the server resolved (what `<FlagsScript>` carries), skipping any resolution. */
  hydrate(values: Partial<FlagValues<D>>): void;
  /** Every current value, as one frozen object that stays the same until the next change. */
  snapshot(): FlagValues<D>;
  /** Call `listener` after each resolve or hydrate that updates the snapshot; returns the unsubscribe. */
  subscribe(listener: () => void): () => void;
  /** The definitions passed in. */
  readonly definitions: D;
  /** Whether the snapshot came from a resolve or hydrate rather than the defaults. */
  readonly resolved: boolean;
}
```

The flags service bound as `flags`: a typed snapshot of every flag, and the means to resolve it.

### FlagsConfig

```ts
interface FlagsConfig {
  /** The flags from `app/flags.ts`. */
  definitions?: FlagDefinitions;
  /** First provider with an answer wins. */
  providers?: FlagsProvider[];
  /** Seconds a resolved snapshot stays fresh in the browser. Declared for a coming refresh; not read yet. */
  ttl?: number;
}
```

The options in `config/flags.ts`.

### FlagsProvider

```ts
interface FlagsProvider {
  /** Shown in warnings when the provider fails. */
  name: string;
  /** Runs once per `resolve()`, before any key. A throw skips this provider for that resolve. */
  init?(context: FlagContext): Promise<void> | void;
  /** `undefined` means "no opinion": the next provider, then the default, answer. */
  resolve(key: string, context: FlagContext): Promise<FlagValue | undefined> | FlagValue | undefined;
}
```

Where answers come from. Mirrors OpenFeature's provider shape, so an OpenFeature client is a
one-line adapter, but a plain object or `envFlagsProvider()` also work.

### FlagDefinitions

```ts
type FlagDefinitions = Record<string, FlagDefinition>;
```

Every flag by key, as `defineFlags()` takes and returns them.

### FlagMap

```ts
type FlagMap = Record<string, FlagValue>;
```

Flag values by key, untyped: what providers and embedded snapshots carry.

### FlagValue

```ts
type FlagValue = boolean | string | number;
```

A flag's value: on/off, a number such as a limit, or a string such as a variant name.

### FlagValues

```ts
type FlagValues<D extends FlagDefinitions> = {
  [K in keyof D]: D[K]['default'];
};
```

The resolved value of every flag in `D`, typed by each default.

## kitr/flags/react

### FlagsScript

```ts
function FlagsScript({ values }: {
  values: Record<string, unknown>;
}): import("react").DetailedReactHTMLElement<{
  type: string;
  id: string;
  dangerouslySetInnerHTML: {
    __html: string;
  };
}, HTMLElement>;
```

Put in the document head of the root route with the values `resolveFlags()` returned in the loader.

### useFlag

```ts
function useFlag<D extends FlagDefinitions, K extends keyof D & string>(key: K): D[K]['default'];
```

One flag's value; re-renders when a resolve or hydrate changes it.

### useFlags

```ts
function useFlags<D extends FlagDefinitions = FlagDefinitions>(): FlagValues<D>;
```

Every flag, as a plain object.

## kitr/flags/provider

### flagsProvider

```ts
const flagsProvider: import("@kitr/core").KitrProvider;
```

Binds `flags` from `config/flags.ts` (`definitions` from `app/flags.ts`, `providers`). In the
browser a snapshot embedded by `<FlagsScript>` loads before the first render; otherwise
`resolve()` runs at boot. On the server, `resolveFlags(app, event)` answers per request.

## kitr/flags/server

### flagsScript

```ts
function flagsScript(values: Record<string, unknown>): string;
```

The server-resolved snapshot as a script tag the client provider reads before hydration.

### resolveFlags

```ts
function resolveFlags<D extends FlagDefinitions>(app: KitrApp, event: H3Event | {
  context: Record<string, any>;
}, context?: FlagContext): Promise<FlagValues<D>>;
```

Resolve every flag for this request (user from `event.context.kitr.locals.user` when auth ran),
cached on the event so loaders, controllers and the page share one answer.

### Flags

```ts
interface Flags<D extends FlagDefinitions = FlagDefinitions> {
  /** The current answer. Synchronous: works from a resolved snapshot (and the defaults before one). */
  value<K extends keyof D & string>(key: K): D[K]['default'];
  /** True only when the flag's current value is exactly `true`. */
  isEnabled(key: keyof D & string): boolean;
  /** Every flag, resolved for `context`. Server: once per request. Client: once per session, then cached. */
  resolve(context?: FlagContext): Promise<FlagValues<D>>;
  /** Load a snapshot the server resolved (what `<FlagsScript>` carries), skipping any resolution. */
  hydrate(values: Partial<FlagValues<D>>): void;
  /** Every current value, as one frozen object that stays the same until the next change. */
  snapshot(): FlagValues<D>;
  /** Call `listener` after each resolve or hydrate that updates the snapshot; returns the unsubscribe. */
  subscribe(listener: () => void): () => void;
  /** The definitions passed in. */
  readonly definitions: D;
  /** Whether the snapshot came from a resolve or hydrate rather than the defaults. */
  readonly resolved: boolean;
}
```

The flags service bound as `flags`: a typed snapshot of every flag, and the means to resolve it.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Feature flags

Source: https://kitr.dev/packages/flags

Feature flags let you merge unfinished work behind a switch, turn a redesign on for 10% of users, or switch a feature off in production without a deploy. `kitr/flags` declares every flag once, with a typed default, so a misspelt flag is a type error. Providers decide each flag's value per user: an env variable, a stable percentage rollout, your own rules, or any [OpenFeature](https://openfeature.dev/docs/reference/intro) vendor such as LaunchDarkly, Flagsmith or Unleash.

On top of that provider chain kitr adds type coercion, so `FLAG_MAX_UPLOAD_MB=25` arrives as a number, a per-request answer on the server that never leaks from one user to another, and a snapshot the server embeds so the browser starts with the same values.

It runs on both sides: React hooks in the browser, `resolveFlags()` on the server. Flags are not permissions. To decide whether Grace may delete an invoice, use [auth](/packages/auth) abilities. For a value that is the same for everyone in an environment, a [config file](/docs/configuration) is simpler.

The examples on this page follow Acme's dashboard at `app.acme.com`, which is rolling out a redesigned dashboard (`new-dashboard`) and raising the upload limit for invoices (`max-upload-mb`).

## Install

```sh
kitr add flags
```

What `kitr add` does:

- Adds `@kitr/flags` to `dependencies` in `package.json` and installs it. Pass `--no-install` to skip the install.
- Adds `() => import('@kitr/flags/provider')` to `providers` and `'@kitr/flags'` to `packages` in `kitrrc.ts`. The provider binds `flags` in the container.
- Writes `app/flags.ts`, which declares two example flags, and `config/flags.ts`, which lists the providers (see [Configure](#configure)).
- Adds a `## kitr: flags` section to `AGENTS.md`. In a project with React it says: flags live in `app/flags.ts`, components read `useFlag('new-dashboard')` from `kitr/flags/react`, the server resolves them per request with `resolveFlags` and embeds them with `<FlagsScript />`, and feature switches never read `import.meta.env`. In a server-only project it says: resolve per request with `resolveFlags(app, event, { userId })` from `kitr/flags/server`, providers ordered in `config/flags.ts`.

It adds no env variables, no scripts and asks no questions. No kit includes flags, so every project adds it with this command.

`kitr remove flags` takes the provider and the package out of `kitrrc.ts`, deletes `config/flags.ts`, removes the dependency and the `AGENTS.md` section. It keeps `app/flags.ts`, because your code imports from it; delete it once nothing does.

## Configure

`kitr add flags` writes two files. The flags themselves:

```ts
// app/flags.ts
import { defineFlags } from 'kitr/flags'

/** Every flag with its default, so unknown flags are a type error. */
export const flags = defineFlags({
  'new-dashboard': { default: false, description: 'The redesigned dashboard' },
  'max-upload-mb': { default: 10 },
})
```

And where their values come from:

```ts
// config/flags.ts
import { defineConfig, envFlagsProvider, percentageFlagsProvider } from 'kitr/flags'
import { flags } from '#app/flags'

export default defineConfig({
  definitions: flags,
  // First provider with an answer wins: FLAG_NEW_DASHBOARD=true in .env, then a 10% rollout.
  providers: [envFlagsProvider(), percentageFlagsProvider({ 'new-dashboard': 10 })],
  // openFeatureFlagsProvider(client) plugs in LaunchDarkly, Flagsmith, Unleash... through OpenFeature.
})
```

| Option | Default | Description |
| --- | --- | --- |
| `definitions` | `{}` | The flags from `app/flags.ts`. A flag not listed here has no value. |
| `providers` | `[]` | Asked in order for each flag; the first with an answer wins. With none, every flag is its default. |
| `ttl` | `300` | Declared for a future browser refresh. This version does not read it. |

For each flag, the providers are asked in order. The first that answers with a value of the right type wins. If none does, the flag's `default` from `app/flags.ts` answers. A provider that throws is skipped with a `console.warn`, so a flag service outage falls back to defaults instead of breaking pages.

`envFlagsProvider()` reads one variable per flag. The name is `FLAG_` plus the flag key in upper case, with dashes, dots and camelCase humps turned into underscores:

| Variable | Used for |
| --- | --- |
| `FLAG_NEW_DASHBOARD` | `new-dashboard`: `true`, `1`, `on` or `yes` turn it on; `false`, `0`, `off`, `no` or empty turn it off. |
| `FLAG_MAX_UPLOAD_MB` | `max-upload-mb`: any finite number, such as `25`. |

The env provider reads `process.env`, so it answers on the server. In the browser there is no `process.env` and it stays silent, which is why the server's snapshot matters (see [Send the server's answer to the browser](#send-the-servers-answer-to-the-browser)).

## Show a feature to some users

In a component, `useFlag` from `kitr/flags/react` returns a flag's current value and re-renders when it changes:

```tsx
// app/features/dashboard/dashboard_page.tsx
import { useFlag } from 'kitr/flags/react'
import type { flags } from '#app/flags'
import { ClassicDashboard } from './classic_dashboard'
import { NewDashboard } from './new_dashboard'

export function DashboardPage() {
  const redesigned = useFlag<typeof flags, 'new-dashboard'>('new-dashboard')
  return redesigned ? <NewDashboard /> : <ClassicDashboard />
}
```

Put `FLAG_NEW_DASHBOARD=true` in `.env`, restart the server, and the dashboard switches for everyone. Remove the line and 10% of signed-in users, chosen by user id, still see the redesign through the percentage provider. Everyone else, and every signed-out visitor, sees the classic one.

## Declare flags

Every flag lives in `app/flags.ts`. The `default` sets both the value when no provider answers and the flag's type:

```ts
// app/flags.ts
import { defineFlags } from 'kitr/flags'

export const flags = defineFlags({
  'new-dashboard': { default: false, description: 'The redesigned dashboard' },
  'max-upload-mb': { default: 10, description: 'Largest invoice PDF a team may upload' },
  'invoice-layout': { default: 'classic', description: "'classic' or 'compact' invoice PDFs" },
})
```

| Default | Flag type | Typical use |
| --- | --- | --- |
| `false` | `boolean` | Show or hide a feature. |
| `10` | `number` | A limit or a size. |
| `'classic'` | `string` | A variant name for an experiment. |

`defineFlags` returns its argument with its exact types, so `useFlag<typeof flags, 'max-upload-mb'>` is a `number` and a key that isn't declared is a type error. Write `description` for the person who flips the flag in six months; it is the only documentation a flag gets.

Choose defaults that are safe to fall back to. If the flag service is down, every user gets the default, so a half-finished feature should default to `false`.

## Type the hooks once

`useFlag` needs the flags type to check keys. Instead of repeating `typeof flags` in every component, wrap it once next to the declarations:

```ts
// app/use_flag.ts
import { useFlag } from 'kitr/flags/react'
import type { flags } from '#app/flags'

type AcmeFlags = typeof flags

/** `useAcmeFlag('max-upload-mb')` is a number; an unknown key is a type error. */
export function useAcmeFlag<K extends keyof AcmeFlags & string>(key: K) {
  return useFlag<AcmeFlags, K>(key)
}
```

```tsx
// app/features/invoices/upload_hint.tsx
import { useAcmeFlag } from '#app/use_flag'

export function UploadHint() {
  const maxMb = useAcmeFlag('max-upload-mb')
  return <p>PDFs up to {maxMb} MB.</p>
}
// => <p>PDFs up to 10 MB.</p>   (no provider answered, so the default)
```

Calling `useFlag('max-upload-mb')` with no type arguments also works, but the value is typed as `boolean | string | number` and a typo is not caught.

## Read every flag at once

`useFlags()` from `kitr/flags/react` returns every flag as one object, for a settings page or a debug panel:

```tsx
// app/features/settings/flags_panel.tsx
import { useFlags } from 'kitr/flags/react'
import type { flags } from '#app/flags'

export function FlagsPanel() {
  const values = useFlags<typeof flags>()
  return <pre>{JSON.stringify(values, null, 2)}</pre>
}
// => { "new-dashboard": false, "max-upload-mb": 10, "invoice-layout": "classic" }
```

The object is frozen and stays the same object until the flags change, so it is safe to pass to memoised children.

## Read a flag outside React

Outside components, get the service from the container with `useFlags(app)` from `kitr/flags`. Its reads are synchronous and answer from the current snapshot:

```ts
// app/features/invoices/validate_upload.ts
import type { KitrApp } from 'kitr/app'
import { useFlags } from 'kitr/flags'
import type { flags } from '#app/flags'

export function checkUploadSize(app: KitrApp, file: File) {
  const maxMb = useFlags<typeof flags>(app).value('max-upload-mb')
  if (file.size > maxMb * 1024 * 1024) return `Invoices must be under ${maxMb} MB.`
  return null
}
```

| Method | Returns | Description |
| --- | --- | --- |
| `value(key)` | the flag's type | The current value: the snapshot, or the default before one exists. |
| `isEnabled(key)` | `boolean` | `true` only when the value is exactly `true`. |
| `snapshot()` | all values | One frozen object with every flag. |
| `resolve(context?)` | `Promise` of all values | Ask the providers for `context`. See below. |
| `hydrate(values)` | `void` | Load values the server resolved. |
| `subscribe(listener)` | unsubscribe function | Called after each resolve or hydrate that updates the snapshot. |
| `resolved` | `boolean` | Whether the snapshot came from a resolve or hydrate rather than defaults. |
| `definitions` | the definitions | What `app/flags.ts` declared. |

`isEnabled` is for boolean flags. On a number flag it is always `false`, even for a value of `1`; use `value()` there.

## Read flags on the server

On the server, one process answers many users at once, so flags are resolved per request. `resolveFlags(app, event, context)` from `kitr/flags/server` asks the providers for this request's user and caches the answer on the request:

```ts
// server/controllers/dashboard_controller.ts
import type { HttpContext } from 'kitr/api'
import { resolveFlags } from 'kitr/flags/server'
import type { flags } from '#app/flags'
import { classicSummary, newSummary } from '#server/dashboard/summaries'

export default class DashboardController {
  async show({ app, event }: HttpContext) {
    const values = await resolveFlags<typeof flags>(app, event)
    return values['new-dashboard'] ? newSummary() : classicSummary()
  }
}
```

The user comes from `locals.user.id` when [auth](/packages/auth) middleware has set it, so a percentage rollout gives Ada the same answer on every request. Pass more context as the third argument; it is merged over the user id and every provider receives it:

```ts
// server/controllers/invoices_controller.ts
import type { HttpContext } from 'kitr/api'
import { resolveFlags } from 'kitr/flags/server'
import type { flags } from '#app/flags'

export default class InvoicesController {
  async uploadLimit({ app, event, locals }: HttpContext) {
    const team = locals.team as { id: string; plan: 'free' | 'pro' }
    const values = await resolveFlags<typeof flags>(app, event, { teamId: team.id, plan: team.plan })
    return { maxMb: values['max-upload-mb'] }
    // => { maxMb: 10 }
  }
}
```

The first call on a request runs the providers; later calls on the same request return the same object without asking again, even with different context. Resolve once, early, with the full context.

Inside a request, the request's own app (a fork of the server app) keeps the resolved values, so `useFlags(app).value('new-dashboard')` in a service called from that request answers for that user. The shared root app never keeps a resolved snapshot: `resolve()` on it returns the values but leaves `value()` at the defaults, so one user's answer can never leak to the next.

## Send the server's answer to the browser

The browser can't read `process.env`, and it may not know the user id when it boots. So the server resolves the flags and embeds the result in the page as a JSON script tag. When the client app boots, the flags provider reads that tag and loads it before the first render, without asking any provider.

`<FlagsScript values={...} />` from `kitr/flags/react` renders the tag. In a server-rendered app, resolve in the root route's loader and put the tag in the document head:

```ts
// app/server/load_flags.ts
import { createServerFn } from 'kitr/actions'
import { resolveFlags } from 'kitr/flags/server'
import type { flags } from '#app/flags'
import { server } from '#server/main'
import { currentUserId } from '#server/session'

export const loadFlags = createServerFn({ method: 'GET' }).handler(async () => {
  await server.boot()
  return resolveFlags<typeof flags>(server.app, { context: {} }, { userId: await currentUserId() })
})
```

```tsx
// app/routes/__root.tsx
import { FlagsScript } from 'kitr/flags/react'
import type { KitrRouterContext } from 'kitr/router'
import { HeadContent, Outlet, Scripts, createRootRouteWithContext } from 'kitr/router'
import { loadFlags } from '#app/server/load_flags'

export const Route = createRootRouteWithContext<KitrRouterContext>()({
  loader: () => loadFlags(),
  component: RootDocument,
})

function RootDocument() {
  const flags = Route.useLoaderData()
  return (
    <html lang="en">
      <head>
        <HeadContent />
        <FlagsScript values={flags} />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}
```

The page now carries:

```html
<script type="application/json" id="__kitr_flags__">{"new-dashboard":true,"max-upload-mb":10}</script>
```

Values are escaped (`<` becomes `<`), so a string flag can't close the tag. The client treats the embedded JSON as input: it keeps only declared keys, coerces each to its declared type, and falls back to the default for anything it can't read. A broken tag is ignored, and the provider resolves at boot instead.

Outside React, `flagsScript(values)` from `kitr/flags/server` returns the same tag as a string, for a server that writes HTML by hand:

```ts
// server/pages/invoice_print.ts
import { flagsScript } from 'kitr/flags/server'

const head = `<head><title>Invoice</title>${flagsScript({ 'invoice-layout': 'compact' })}</head>`
// => <head><title>Invoice</title><script type="application/json" id="__kitr_flags__">{"invoice-layout":"compact"}</script></head>
```

During server rendering, `useFlag` answers from the app that renders the page. When that app has not resolved flags for this request, it renders defaults, and the browser's first render from the embedded snapshot can differ. For UI that must match on the first paint, read the value from the root loader's data on both sides.

In a single-page app with no server rendering, there is nothing to embed. The provider calls `resolve()` at boot in the browser with no context, so env variables and percentage rollouts don't apply until you resolve again with a user (next section).

## Resolve again after sign-in

In the browser, `resolve(context)` updates the snapshot, and every `useFlag` re-renders with the new answer. Call it once you know who the user is:

```tsx
// app/features/auth/after_sign_in.tsx
import { useApp } from 'kitr/react'
import { useEffect } from 'react'

export function ResolveFlagsFor({ userId }: { userId: string }) {
  const app = useApp()
  useEffect(() => {
    void app.container.use('flags').resolve({ userId })
  }, [app, userId])
  return null
}
```

Render `<ResolveFlagsFor userId={user.id} />` inside the signed-in layout. When Linus signs in, the percentage provider places him in or out of the 10%, and the dashboard switches without a reload. Call `resolve({})` on sign-out to drop back to the anonymous answer.

## Providers

A provider answers flags from one source. List them in `config/flags.ts` in priority order: the first one with an answer wins.

| Provider | Answers from | Silent when |
| --- | --- | --- |
| `envFlagsProvider(env?, prefix?)` | `FLAG_*` env variables | The variable is unset, or can't be read as the flag's type. |
| `percentageFlagsProvider(shares, salt?)` | A stable share of user ids | The flag is not in `shares`. |
| `staticFlagsProvider(values)` | A map, or a function of the context | The map has no entry for the flag. |
| `openFeatureFlagsProvider(client, flags)` | Any OpenFeature client | Never: the client returns its own default. |

### Env variables

Built in; nothing to install. Good for turning a flag on per environment, or forcing it in staging:

```ts
// config/flags.ts
import { defineConfig, envFlagsProvider } from 'kitr/flags'
import { flags } from '#app/flags'

export default defineConfig({
  definitions: flags,
  providers: [envFlagsProvider()],
})
```

```sh
FLAG_NEW_DASHBOARD=true
FLAG_MAX_UPLOAD_MB=25
```

Pass a map as the first argument to read from somewhere other than `process.env`, and a prefix as the second: `envFlagsProvider(process.env, 'ACME_FLAG_')` reads `ACME_FLAG_NEW_DASHBOARD`. Changing an env variable needs a server restart.

### Percentage rollout

Built in. Turns a flag on for a share of users, from 0 to 100:

```ts
// config/flags.ts
import { defineConfig, envFlagsProvider, percentageFlagsProvider } from 'kitr/flags'
import { flags } from '#app/flags'

export default defineConfig({
  definitions: flags,
  providers: [envFlagsProvider(), percentageFlagsProvider({ 'new-dashboard': 25 }, 'dashboard-2026')],
})
```

The answer is a hash of the salt, the flag key and the user id, so Ada gets the same answer on every request and every server. Raising 25 to 50 keeps everyone who already had the feature and adds more. Two flags at 50% reach different, independent halves of your users. Change the salt to draw a new sample.

With no `userId` in the context, the provider answers `false`, and since that is an answer, providers after it are not asked. Put overrides such as `envFlagsProvider()` before it.

### Static rules

Built in. A fixed map, or a function of the context for rules you write in code:

```ts
// config/flags.ts
import { defineConfig, envFlagsProvider, staticFlagsProvider } from 'kitr/flags'
import { flags } from '#app/flags'

export default defineConfig({
  definitions: flags,
  providers: [
    envFlagsProvider(),
    staticFlagsProvider((context) => ({
      'new-dashboard': context.teamId === 'design',
      'max-upload-mb': context.plan === 'pro' ? 100 : undefined,
    })),
  ],
})
```

The design team sees the new dashboard. Pro teams get 100 MB; for everyone else `undefined` means "no opinion", so the default of 10 answers. The context holds `userId` plus whatever you passed to `resolveFlags` or `resolve`.

### OpenFeature

Connect any vendor that has an [OpenFeature provider](https://openfeature.dev/ecosystem): LaunchDarkly, Flagsmith, Unleash, GrowthBook, ConfigCat and others. Install the SDK for the side you resolve on, plus your vendor's provider:

```sh
pnpm add @openfeature/server-sdk
```

```ts
// config/flags.ts
import { InMemoryProvider, OpenFeature } from '@openfeature/server-sdk'
import { defineConfig, envFlagsProvider, openFeatureFlagsProvider } from 'kitr/flags'
import { flags } from '#app/flags'

// Replace InMemoryProvider with your vendor's provider, configured with its SDK key.
OpenFeature.setProvider(
  new InMemoryProvider({
    'new-dashboard': { variants: { on: true, off: false }, defaultVariant: 'on', disabled: false },
  }),
)

export default defineConfig({
  definitions: flags,
  providers: [envFlagsProvider(), openFeatureFlagsProvider(OpenFeature.getClient(), flags)],
})
```

The adapter calls `getBooleanValue`, `getNumberValue` or `getStringValue` depending on each flag's declared default, passing the default and the context with `targetingKey` set to `userId`. Your vendor's key goes in `.env` as the vendor's docs say, for example `LAUNCHDARKLY_SDK_KEY=sdk-...`. Because an OpenFeature client always answers (with the default when it has no rule), put it last.

## Values a provider can return

Providers often answer with strings, from env files or remote JSON. Each answer is coerced to the flag's declared type; an answer that can't be read as that type counts as no answer, and the next provider is asked:

| Declared type | Accepted answers | Ignored answers |
| --- | --- | --- |
| `boolean` | `true`/`false`; `'true'`, `'1'`, `'on'`, `'yes'`; `'false'`, `'0'`, `'off'`, `'no'`, `''`; numbers (0 is false) | `'maybe'` |
| `number` | Numbers; strings that parse to a finite number, such as `' 7.5 '` | `'lots'`, `''`, `'12px'`, `'Infinity'`, booleans |
| `string` | Strings; numbers and booleans, turned into strings | None |

```ts
// scripts/coercion_demo.ts
import { createFlags, envFlagsProvider, staticFlagsProvider } from 'kitr/flags'
import { flags } from '#app/flags'

const demo = createFlags(flags, {
  providers: [
    envFlagsProvider({ FLAG_NEW_DASHBOARD: 'yes', FLAG_MAX_UPLOAD_MB: 'lots' }),
    staticFlagsProvider({ 'max-upload-mb': 50 }),
  ],
})
await demo.resolve()
// => { 'new-dashboard': true, 'max-upload-mb': 50, 'invoice-layout': 'classic' }
```

`'lots'` is not a number, so the env provider's answer is ignored and the static provider's `50` wins.

## Retire a flag

A flag is finished when the feature has shipped to everyone. Delete it from `app/flags.ts`:

```ts
// app/flags.ts
import { defineFlags } from 'kitr/flags'

export const flags = defineFlags({
  'max-upload-mb': { default: 10, description: 'Largest invoice PDF a team may upload' },
  'invoice-layout': { default: 'classic', description: "'classic' or 'compact' invoice PDFs" },
})
```

Every typed `useFlag<typeof flags, 'new-dashboard'>` and `resolveFlags<typeof flags>` read of it is now a type error, which lists the code to clean up. Remove the old branch, then the `FLAG_NEW_DASHBOARD` line and the `'new-dashboard'` share in `config/flags.ts`.

## Devtools

When the [devtools](/packages/devtools) package is installed, every resolve or hydrate that updates the snapshot logs `resolved` with all values to the `flags` channel. It shows which values the browser booted with, and whether they came from the server's tag.

## Testing

`createFlags(definitions, config)` builds a flags service with no app. Give it a `staticFlagsProvider` to test both sides of a flag:

```ts
// app/features/invoices/validate_upload.test.ts
import { createFlags, staticFlagsProvider } from 'kitr/flags'
import { describe, expect, it } from 'vitest'
import { flags } from '#app/flags'

describe('upload limit flag', () => {
  it('answers the default until resolved, then the provider', async () => {
    const service = createFlags(flags, { providers: [staticFlagsProvider({ 'max-upload-mb': 25 })] })
    expect(service.value('max-upload-mb')).toBe(10)
    expect(service.resolved).toBe(false)

    expect(await service.resolve({ userId: 'ada' })).toEqual({
      'new-dashboard': false,
      'max-upload-mb': 25,
      'invoice-layout': 'classic',
    })
    expect(service.value('max-upload-mb')).toBe(25)
  })

  it('targets by context', async () => {
    const service = createFlags(flags, {
      providers: [staticFlagsProvider((ctx) => ({ 'new-dashboard': ctx.userId === 'grace' }))],
    })
    expect((await service.resolve({ userId: 'grace' }))['new-dashboard']).toBe(true)
    expect((await service.resolve({ userId: 'linus' }))['new-dashboard']).toBe(false)
  })
})
```

To render a component with a flag set, boot a client app with the flags provider and render it with `renderWithKitr` from [testing](/packages/testing). The provider resolves at boot on the client, so the first render already has the value:

```tsx
// app/features/dashboard/dashboard_page.test.tsx
import { defineConfig, staticFlagsProvider } from 'kitr/flags'
import flagsProvider from 'kitr/flags/provider'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { screen } from '@testing-library/react'
import { expect, it } from 'vitest'
import { flags } from '#app/flags'
import { DashboardPage } from './dashboard_page'

// NewDashboard renders <h1>Your new dashboard</h1>.
it('shows the new dashboard when the flag is on', async () => {
  const app = await createTestApp({
    environment: 'client',
    providers: [flagsProvider],
    config: {
      flags: defineConfig({ definitions: flags, providers: [staticFlagsProvider({ 'new-dashboard': true })] }),
    },
  })
  renderWithKitr(<DashboardPage />, { app })
  expect(screen.getByRole('heading', { name: 'Your new dashboard' })).toBeTruthy()
})
```

Pass `environment: 'client'`. In the default `test` environment the provider does not resolve at boot, and the root app does not keep a resolved snapshot, as on the server.

To flip a flag mid-test, call `app.container.use('flags').hydrate({ 'new-dashboard': false })` inside `act()`; subscribed components re-render.

## Extend

A provider is an object with a `name`, an optional `init(context)` and `resolve(key, context)`:

| Member | Called | Returns |
| --- | --- | --- |
| `name` | In warnings | A label, such as `database`. |
| `init(context)` | Once per `resolve()`, before any key | Nothing. A throw skips the provider for this resolve. |
| `resolve(key, context)` | Once per declared flag | A value, or `undefined` for "no opinion". May be async. |

`init` is the place to load everything a provider needs for one context in a single request, so `resolve` can answer from memory. This provider reads per-team overrides that Acme's support staff publish as JSON at `https://flags.acme.com/teams/<teamId>.json`:

```ts
// app/flag_providers/team_overrides.ts
import type { FlagsProvider, FlagValue } from 'kitr/flags'

/** Overrides by team, from https://flags.acme.com/teams/<teamId>.json: { "new-dashboard": true }. */
export function teamOverridesProvider(baseUrl = 'https://flags.acme.com/teams'): FlagsProvider {
  const byTeam = new Map<string, Record<string, FlagValue>>()
  return {
    name: 'team-overrides',
    async init(context) {
      const teamId = context.teamId as string | undefined
      if (!teamId || byTeam.has(teamId)) return
      const response = await fetch(`${baseUrl}/${encodeURIComponent(teamId)}.json`)
      if (!response.ok) throw new Error(`flag overrides for ${teamId}: HTTP ${response.status}`)
      byTeam.set(teamId, (await response.json()) as Record<string, FlagValue>)
    },
    resolve(key, context) {
      const teamId = context.teamId as string | undefined
      return teamId ? byTeam.get(teamId)?.[key] : undefined
    },
  }
}
```

When the file can't be fetched, `init` throws, the provider is skipped for that resolve with a warning, and the next provider answers. This sketch keeps loaded teams for the life of the process; clear `byTeam` on a timer when overrides must change without a restart. Register the provider in priority order:

```ts
// config/flags.ts
import { defineConfig, envFlagsProvider, percentageFlagsProvider } from 'kitr/flags'
import { flags } from '#app/flags'
import { teamOverridesProvider } from '#app/flag_providers/team_overrides'

export default defineConfig({
  definitions: flags,
  providers: [envFlagsProvider(), teamOverridesProvider(), percentageFlagsProvider({ 'new-dashboard': 10 })],
})
```

The same config runs in the browser, which is why this provider uses `fetch` and an absolute URL rather than a database client. Keep server-only imports out of `config/flags.ts`. See [`FlagsProvider`](/packages/flags/api#flagsprovider) in the API reference.

## Next steps

- [API reference](/packages/flags/api): every export with its signature.
- [OpenFeature](https://openfeature.dev/docs/reference/intro): the vendor-neutral flag standard the adapter speaks.
- [Auth](/packages/auth): the signed-in user whose id targets rollouts.
- [Cache](/packages/cache): remember slow server reads between requests.
- [Configuration](/docs/configuration): how `config/flags.ts` is loaded.


# Forms API

Source: https://kitr.dev/packages/forms/api

`kitr/forms` re-exports everything from `react-hook-form` (its `Form` as `RhfForm`) and adds the following.

## useSchemaForm

```ts
function useSchemaForm<TIn, TOut = TIn>(
  schema: StandardSchemaV1<TIn, TOut>,
  options?: Omit<UseFormProps<TIn, unknown, TOut>, 'resolver'>,
): UseFormReturn<TIn, unknown, TOut>
```

`useForm` with a Standard Schema resolver and `mode: 'onTouched'`. Every React Hook Form option is accepted. `useZodForm` is an alias.

## Form

```tsx
<Form form={form} onSubmit={fn} onSuccess? onError? resetOnSuccess? {...formAttributes}>
```

| Prop | Type | Description |
| --- | --- | --- |
| `form` | `UseFormReturn` | From `useSchemaForm` or `useForm`. |
| `onSubmit` | `(values: TOut) => unknown` | Runs with validated values. Throw or reject to report errors. |
| `onSuccess` | `(result, values) => void` | Runs after `onSubmit` resolves. |
| `onError` | `(error: KitrError) => void` | Runs after errors are applied to fields. |
| `resetOnSuccess` | `boolean` | Reset to default values after success. |

Any other prop goes to the `<form>` element, which always has `noValidate`.

## FormField

```tsx
<FormField name="email" label="Email" description="We never share it." className="...">
  {children | ({ id, name, invalid, describedBy }) => ReactNode}
</FormField>
```

Renders a wrapper with `data-kitr="field"` (and `data-invalid` when it has an error), a `<label>`, the description and the error message with `role="alert"`. It is headless: style it with your own classes or the `data-kitr` attributes.

## useFieldProps and FieldInput

```ts
useFieldProps(): { id, 'aria-invalid', 'aria-describedby', name, onChange, onBlur, ref }
```

Props for the input inside the nearest `<FormField>`, including `form.register(name)`. `<FieldInput {...inputProps} />` is an `<input>` with these applied.

## SubmitButton

```tsx
<SubmitButton pendingText="Saving…">Save</SubmitButton>
```

A `type="submit"` button, disabled with `aria-busy` while the form submits.

## useFormStatus and useRootError

```ts
useFormStatus(): { pending: boolean; isValid: boolean }
useRootError(): string | undefined
```

## applyServerErrors

```ts
function applyServerErrors(form: UseFormReturn, error: unknown): boolean
```

Maps a `KitrError`'s `fieldErrors` onto fields and everything else to `root.server`. `<Form>` calls it for you; use it when submitting another way. Returns `true` for validation errors.


# Forms

Source: https://kitr.dev/packages/forms

Sign-up pages, invoice editors and settings screens all need the same three things: check the input before it is sent, stop a second click while it saves, and show the server's "this customer does not exist" under the right field instead of in a generic alert. `kitr/forms` gives you all three from one schema and one `<Form>` component.

It is [React Hook Form](https://react-hook-form.com) re-exported unchanged, plus `useSchemaForm` (React Hook Form with a [Standard Schema](https://standardschema.dev) resolver), a `<Form>` that maps server errors onto fields, and headless, accessible field helpers. Everything on this page runs in the browser. For the server half of a form, see [server actions](/packages/actions) or [API routes](/packages/api); `kitr/forms` does not run on the server.

The examples follow one form through the page: Ada creates invoices for Acme's customers in the app at `app.acme.com`.

## Install

```sh
kitr add forms
```

What `kitr add` does:

- Installs `@kitr/forms`, `react-hook-form`, `@hookform/resolvers` and `zod`.
- Adds `@kitr/forms` to `packages` in `kitrrc.ts`.
- Adds a `## kitr: forms` section to `AGENTS.md` that tells agents to build forms with `useSchemaForm` and `<Form>`, and that a `KitrError` with `fieldErrors` lands on fields while anything else goes to `useRootError()`.

It writes no config file, registers no provider, adds no env variables and asks no questions. The `app` and `fullstack` kits already include forms, along with the styled `form` component described in [Style fields](#style-fields).

In a server-only project `kitr add` skips forms with a warning, because it needs React. `kitr remove forms` removes the package from `kitrrc.ts`, uninstalls `@kitr/forms`, `react-hook-form` and `@hookform/resolvers`, and removes the `AGENTS.md` section. It leaves `zod` installed, because your server code usually uses it too.

## Configure

`kitr/forms` has no config file. Each form is set up where you write it, with `useSchemaForm` and `<Form>`:

```tsx
// app/features/invoices/new-invoice-form.tsx
import { Form, useSchemaForm } from 'kitr/forms'
import { newInvoiceSchema } from './schema'

export function NewInvoiceForm({ onCreate }: { onCreate: (values: unknown) => Promise<unknown> }) {
  const form = useSchemaForm(newInvoiceSchema, {
    mode: 'onTouched',
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })
  return (
    <Form form={form} onSubmit={onCreate} resetOnSuccess>
      {/* fields */}
    </Form>
  )
}
```

`useSchemaForm(schema, options)` takes every [`useForm` option](https://react-hook-form.com/docs/useform) except `resolver`, which it sets from the schema. These are the ones you use most:

| Option | Default | Description |
| --- | --- | --- |
| `mode` | `'onTouched'` | When a field is validated first: `'onTouched'` waits until it loses focus. React Hook Form's own default is `'onSubmit'`. |
| `reValidateMode` | `'onChange'` | When a field that already failed is checked again. |
| `defaultValues` | `undefined` | The starting values, and what `form.reset()` returns to. Give every field one so inputs stay controlled. |
| `values` | `undefined` | Values that replace the form's values whenever they change, for forms fed by a query. |
| `shouldFocusError` | `true` | Focus the first invalid field on submit. |
| `disabled` | `false` | Disable every registered input. |

`<Form>` takes these props. Any other prop goes on the `<form>` element.

| Option | Default | Description |
| --- | --- | --- |
| `form` | required | The object `useSchemaForm` (or `useForm`) returned. |
| `onSubmit` | required | Runs with the validated, transformed values. Throw or reject to report errors. |
| `onSuccess` | `undefined` | `(result, values) => void`. Runs after `onSubmit` resolves, with what it returned. |
| `onError` | `undefined` | `(error: KitrError) => void`. Runs after a thrown error has been put on the fields. |
| `resetOnSuccess` | `false` | Call `form.reset()` after a successful submit, which returns every field to `defaultValues`. |
| `noValidate` | `true` | Turns off the browser's own validation bubbles so the schema's messages are the only ones. |

## Build your first form

Start with a schema. Put it in its own file so the server can import the same one.

```ts
// app/features/invoices/schema.ts
import { z } from 'zod'

export const newInvoiceSchema = z.object({
  customerEmail: z.email('Enter the customer’s email'),
  amount: z.coerce.number().positive('Amount must be more than zero'),
  dueOn: z.iso.date('Pick a due date'),
})

export type NewInvoice = z.output<typeof newInvoiceSchema>
```

Then the form. Each field is a `<FormField>` with an input inside it.

```tsx
// app/features/invoices/new-invoice-form.tsx
import { FieldInput, Form, FormField, SubmitButton, useRootError, useSchemaForm } from 'kitr/forms'
import { type NewInvoice, newInvoiceSchema } from './schema'

export function NewInvoiceForm({ onCreate }: { onCreate: (invoice: NewInvoice) => Promise<unknown> }) {
  const form = useSchemaForm(newInvoiceSchema, {
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })

  return (
    <Form form={form} onSubmit={onCreate} resetOnSuccess aria-label="New invoice">
      <FormField name="customerEmail" label="Customer email">
        <FieldInput type="email" autoComplete="off" />
      </FormField>
      <FormField name="amount" label="Amount (USD)">
        <FieldInput inputMode="decimal" />
      </FormField>
      <FormField name="dueOn" label="Due on" description="Customers see this date on the invoice.">
        <FieldInput type="date" />
      </FormField>
      <RootError />
      <SubmitButton pendingText="Creating…">Create invoice</SubmitButton>
    </Form>
  )
}

function RootError() {
  const error = useRootError()
  return error ? <p role="alert">{error}</p> : null
}
```

Render it from a route and give it something to do on submit:

```tsx
// app/routes/invoices/new.tsx
import { createFileRoute } from '@tanstack/react-router'
import { NewInvoiceForm } from '#app/features/invoices/new-invoice-form'

export const Route = createFileRoute('/invoices/new')({
  component: () => (
    <NewInvoiceForm onCreate={async (invoice) => console.log('created', invoice)} />
  ),
})
```

Open `/invoices/new`, tab out of the empty email field and "Enter the customer’s email" appears under it. Fill the form with `grace@acme.com`, `120` and a date, press the button, and the console prints:

```js
created { customerEmail: 'grace@acme.com', amount: 120, dueOn: '2026-12-01' }
```

`amount` arrives as the number `120`, not the string from the input, because `onSubmit` receives the schema's output. While `onCreate` runs, the button reads "Creating…" and is disabled. When it resolves, `resetOnSuccess` clears the form.

## Validate with any schema library

`useSchemaForm` accepts any [Standard Schema](https://standardschema.dev): zod, [valibot](https://valibot.dev) or [arktype](https://arktype.io). It wires React Hook Form's `standardSchemaResolver` for you.

```tsx
// app/features/invoices/new-invoice-form.tsx
import * as v from 'valibot'
import { useSchemaForm } from 'kitr/forms'

const newInvoiceSchema = v.object({
  customerEmail: v.pipe(v.string(), v.email('Enter the customer’s email')),
  amount: v.pipe(v.string(), v.transform(Number), v.minValue(0.01, 'Amount must be more than zero')),
  dueOn: v.pipe(v.string(), v.isoDate('Pick a due date')),
})

export function useNewInvoiceForm() {
  return useSchemaForm(newInvoiceSchema, {
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })
}
```

The form has two types. The schema's input type is what the fields hold (`amount` is a string). Its output type is what `onSubmit` receives (`amount` is a number). Both are inferred, so `form.setValue('amount', 120)` is a type error and `values.amount.toFixed(2)` in `onSubmit` is not.

`useZodForm` is the same function under another name, for codebases that already use it. Asynchronous checks work too: a zod `.refine(async ...)` runs on blur and on submit like any other rule.

## Choose when fields are validated

`useSchemaForm` defaults to `mode: 'onTouched'`: a field is checked the first time it loses focus, then on every change until it passes. Nobody sees "Enter the customer’s email" before they had a chance to type it.

```tsx
// app/features/invoices/quick-invoice-form.tsx
import { useSchemaForm } from 'kitr/forms'
import { newInvoiceSchema } from './schema'

export function useQuickInvoiceForm() {
  return useSchemaForm(newInvoiceSchema, {
    mode: 'onSubmit',
    reValidateMode: 'onBlur',
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })
}
```

| `mode` | First check happens |
| --- | --- |
| `'onTouched'` | When the field loses focus (kitr's default). |
| `'onSubmit'` | When the form is submitted (React Hook Form's default). |
| `'onBlur'` | On every blur. |
| `'onChange'` | On every keystroke. Costs a schema run per key. |
| `'all'` | On blur and on change. |

Submitting always validates every field, whatever the mode.

## Submit to your API

`onSubmit` can return any promise. To get the query cache updated as well, pass a [query](/packages/query) mutation's `mutateAsync`. Here the mutation posts to an external API through [http](/packages/http):

```ts
// app/features/invoices/queries.ts
import { defineMutation, defineQuery } from 'kitr/query'
import { httpMutation, httpQuery } from 'kitr/http'
import { app } from '#app/app'
import type { NewInvoice } from './schema'

const http = app.container.use('http')

export const invoiceQuery = defineQuery(
  httpQuery<string, NewInvoice & { id: string }>(http, {
    key: (id) => ['invoices', 'detail', id],
    path: (id) => `invoices/${id}`,
  }),
)

export const createInvoice = defineMutation(
  httpMutation<NewInvoice, { id: string; number: string }>(http, {
    path: 'invoices',
    effects: { invalidate: [['invoices', 'list']] },
  }),
)
```

```tsx
// app/routes/invoices/new.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useKitrMutation } from 'kitr/query'
import { useNavigate } from 'kitr/router'
import { NewInvoiceForm } from '#app/features/invoices/new-invoice-form'
import { createInvoice } from '#app/features/invoices/queries'

export const Route = createFileRoute('/invoices/new')({ component: NewInvoicePage })

function NewInvoicePage() {
  const create = useKitrMutation(createInvoice)
  const navigate = useNavigate()
  return (
    <NewInvoiceForm
      onCreate={async (invoice) => {
        const created = await create.mutateAsync(invoice)
        await navigate({ to: '/invoices/$id', params: { id: created.id } })
      }}
    />
  )
}
```

Use `mutateAsync`, not `mutate`. `mutate` swallows the error, so `<Form>` never sees the server's field errors and the button stops being pending before the request ends.

## Submit to a server action

In a project with [server actions](/packages/actions), the action validates with the same schema on the server:

```ts
// app/actions/invoices/create_invoice.ts
import { defineAction } from 'kitr/actions'
import { newInvoiceSchema } from '#app/features/invoices/schema'

export const createInvoice = defineAction('invoices.createInvoice', {
  input: newInvoiceSchema,
  effects: { invalidate: [['invoices', 'list']] },
  handler: async ({ input }) => {
    // save the invoice
    return { id: 'inv_1042', number: 'ACME-1042', ...input }
  },
})
```

```tsx
// app/routes/invoices/new.tsx
import { createFileRoute } from '@tanstack/react-router'
import { defineMutation, useKitrMutation } from 'kitr/query'
import { createInvoice } from '#app/actions/invoices/create_invoice'
import { NewInvoiceForm } from '#app/features/invoices/new-invoice-form'

const createInvoiceMutation = defineMutation(createInvoice.mutation())

export const Route = createFileRoute('/invoices/new')({ component: NewInvoicePage })

function NewInvoicePage() {
  const create = useKitrMutation(createInvoiceMutation)
  return <NewInvoiceForm onCreate={(invoice) => create.mutateAsync(invoice)} />
}
```

If someone bypasses the browser check, the action rejects with `VALIDATION` and the same messages land under the same fields.

## Show server errors on fields

When `onSubmit` throws or rejects, `<Form>` turns the error into a `KitrError` and reads its `fieldErrors`. Each key is a field path, each value a list of messages, and the first message shows under the field:

```ts
// what the server sent back (HTTP 422)
{
  code: 'VALIDATION',
  message: 'Validation failed',
  status: 422,
  fieldErrors: {
    customerEmail: ['No customer with this email'],
    'lines.0.quantity': ['Only 3 left in stock'],
    _root: ['Invoices are locked while the month closes'],
  },
}
```

The rules:

- A key whose first segment is a field in the form (`customerEmail`, or `lines` for `lines.0.quantity`) goes on that field.
- `_root`, and any key the form does not have (`plan`, `billing.vatId` when there is no `billing` field), goes to the root error, which `useRootError()` returns.
- An error without `fieldErrors` (a `CONFLICT`, a `NETWORK` failure, a 500) puts its `message` on the root error.
- Only the first message per field is shown.

You do not have to shape errors yourself. [API routes](/packages/api) answer `422` with `fieldErrors` when a validator fails, [server actions](/packages/actions) do the same when their `input` schema fails, and [http](/packages/http) converts common backend formats, including the AdonisJS and VineJS `errors` array.

## Throw field errors from the server

For a rule the schema cannot check, such as "this customer exists", throw `KitrError.validation` with the field it belongs to:

```ts
// app/actions/invoices/create_invoice.ts
import { defineAction } from 'kitr/actions'
import { KitrError } from 'kitr/app'
import { newInvoiceSchema } from '#app/features/invoices/schema'

const customers = new Set(['grace@acme.com', 'linus@acme.com'])

export const createInvoice = defineAction('invoices.createInvoice', {
  input: newInvoiceSchema,
  handler: async ({ input }) => {
    if (!customers.has(input.customerEmail)) {
      throw KitrError.validation({ customerEmail: ['No customer with this email'] })
    }
    return { id: 'inv_1042', number: 'ACME-1042', ...input }
  },
})
```

Ada sees "No customer with this email" under the email field, with `aria-invalid="true"` on the input. A message for the whole form goes under `_root`:

```ts
throw KitrError.validation({ _root: ['Invoices are locked while the month closes'] })
```

Nested fields use dot paths: `'billing.vatId'` or `'lines.2.quantity'`.

## Show a form-level error

Errors that are not about one field come back from `useRootError()`. It returns the message, or `undefined`. Call it inside `<Form>`:

```tsx
// app/features/invoices/form-alert.tsx
import { useRootError } from 'kitr/forms'

export function FormAlert() {
  const error = useRootError()
  if (!error) return null
  return (
    <p role="alert" className="rounded-md border border-destructive/40 p-3 text-destructive">
      {error}
    </p>
  )
}
```

The root error is cleared each time the form is submitted again. If Ada's connection drops, she sees "Network request failed". If a server action fails with a 500 in production, she sees "Internal server error"; the real message stays in the server log.

## Show a pending state

`<SubmitButton>` is a `type="submit"` button that is disabled and has `aria-busy="true"` while `onSubmit` runs. `pendingText` replaces its label in that time:

```tsx
<SubmitButton pendingText="Creating…" className="btn-primary">
  Create invoice
</SubmitButton>
```

A `disabled` prop you pass is combined with the pending state, never replaced by it, so `disabled={!canInvoice}` keeps the button off and a pending form still cannot submit twice.

For anything else that should react to the submit, call `useFormStatus()` inside `<Form>`:

```tsx
// app/features/invoices/cancel-link.tsx
import { useFormStatus } from 'kitr/forms'
import { Link } from 'kitr/router'

export function CancelLink() {
  const { pending, isValid } = useFormStatus()
  return (
    <Link to="/invoices" disabled={pending} data-ready={isValid || undefined}>
      Cancel
    </Link>
  )
}
```

`pending` is true while `onSubmit` runs or React Hook Form is submitting. `isValid` is React Hook Form's `formState.isValid`.

## Run code after a submit

`onSuccess` runs with what `onSubmit` returned and the submitted values. `onError` runs after the error has been put on the fields, with the error as a `KitrError`. Neither runs when the schema rejects the input in the browser, because `onSubmit` never starts.

```tsx
// app/features/invoices/new-invoice-panel.tsx
import { toast } from 'kitr/theme'
import { Form, useSchemaForm } from 'kitr/forms'
import { newInvoiceSchema } from './schema'

export function NewInvoicePanel({ onCreate }: { onCreate: (v: unknown) => Promise<{ number: string }> }) {
  const form = useSchemaForm(newInvoiceSchema, {
    defaultValues: { customerEmail: '', amount: '', dueOn: '' },
  })
  return (
    <Form
      form={form}
      onSubmit={onCreate}
      onSuccess={(invoice) => toast.success(`Invoice ${(invoice as { number: string }).number} created`)}
      onError={(error) => {
        if (error.code !== 'VALIDATION') toast.error(error.message)
      }}
      resetOnSuccess
    >
      {/* fields */}
    </Form>
  )
}
```

`resetOnSuccess` returns every field to `defaultValues`. Leave it off for edit forms, where the saved values should stay on screen.

## Edit an existing record

Load the record first, then pass it as `defaultValues`. Render the form only once the data is there, so the defaults are right from the first render:

```tsx
// app/routes/invoices/$id.edit.tsx
import { createFileRoute } from '@tanstack/react-router'
import { FieldInput, Form, FormField, SubmitButton, useSchemaForm } from 'kitr/forms'
import { useSuspenseQuery } from 'kitr/query'
import { newInvoiceSchema } from '#app/features/invoices/schema'
import { invoiceQuery } from '#app/features/invoices/queries'

export const Route = createFileRoute('/invoices/$id/edit')({ component: EditInvoicePage })

function EditInvoicePage() {
  const { id } = Route.useParams()
  const { data: invoice } = useSuspenseQuery(invoiceQuery.options(id))
  const form = useSchemaForm(newInvoiceSchema, {
    defaultValues: {
      customerEmail: invoice.customerEmail,
      amount: String(invoice.amount),
      dueOn: invoice.dueOn,
    },
  })
  return (
    <Form form={form} onSubmit={(values) => console.log('save', id, values)}>
      <FormField name="dueOn" label="Due on">
        <FieldInput type="date" />
      </FormField>
      <SubmitButton>Save</SubmitButton>
    </Form>
  )
}
```

To follow data that changes while the form is open, pass `values` instead of `defaultValues`. React Hook Form then resets the form each time `values` changes. `form.formState.isDirty` tells you whether Ada changed anything.

## Use your own inputs

`<FieldInput>` is a plain `<input>`. For a `<select>`, a `<textarea>` or a styled input, call `useFieldProps()` inside `<FormField>` and spread the result:

```tsx
// app/features/invoices/currency-select.tsx
import { useFieldProps } from 'kitr/forms'

export function CurrencySelect() {
  const props = useFieldProps()
  // => { id, 'aria-invalid', 'aria-describedby', name, onChange, onBlur, ref }
  return (
    <select {...props}>
      <option value="USD">US dollar</option>
      <option value="EUR">Euro</option>
    </select>
  )
}
```

```tsx
<FormField name="currency" label="Currency">
  <CurrencySelect />
</FormField>
```

`useFieldProps()` returns the field's `id` (so the `<label>` points at it), `aria-invalid` and `aria-describedby`, plus everything `form.register(name)` returns. Outside a `<FormField>` it throws `[kitr/forms] useFieldProps() must be used inside <FormField>.`

The registered `onChange`, `onBlur`, `name` and `ref` are spread after your own props, so they win. Don't pass `onChange` to `<FieldInput>` to watch a value; it is replaced. Use `form.watch` instead ([Watch a field](#watch-a-field)).

A checkbox works the same way, and its value arrives as a boolean:

```tsx
<FormField name="sendNow" label="Email the invoice to the customer now">
  <FieldInput type="checkbox" />
</FormField>
```

## Lay out a field yourself

`<FormField>` renders the label, then its children, then the description, then the error. To place things differently, pass a function as its child. It receives `{ id, name, invalid, describedBy }`. The function runs inside `<FormField>` itself, so call `form.register` there rather than `useFieldProps()`:

```tsx
// app/features/invoices/note-field.tsx
import { FormField, useFormContext } from 'kitr/forms'

export function NoteField() {
  const form = useFormContext<{ note: string }>()
  return (
    <FormField name="note" label="Note to the customer" description="Up to 500 characters.">
      {({ id, invalid, describedBy }) => (
        <textarea
          id={id}
          rows={4}
          aria-invalid={invalid || undefined}
          aria-describedby={describedBy || undefined}
          {...form.register('note')}
        />
      )}
    </FormField>
  )
}
```

`useFormContext` is React Hook Form's, re-exported from `kitr/forms`. It works anywhere inside `<Form>`.

## Wrap a controlled component

Date pickers, comboboxes and rich-text editors often take `value` and `onChange` but no `ref`. Use React Hook Form's `Controller`, exported from `kitr/forms`:

```tsx
// app/features/invoices/due-date-field.tsx
import { Controller, FormField, useFormContext } from 'kitr/forms'
import { DatePicker } from '#components/date-picker'

export function DueDateField() {
  const form = useFormContext<{ dueOn: string }>()
  return (
    <FormField name="dueOn" label="Due on">
      {({ id, describedBy }) => (
        <Controller
          control={form.control}
          name="dueOn"
          render={({ field }) => (
            <DatePicker id={id} aria-describedby={describedBy} value={field.value} onChange={field.onChange} />
          )}
        />
      )}
    </FormField>
  )
}
```

The field error and the server errors still appear, because they are keyed by name, not by input.

## Repeat fields

Invoice lines are a list. `useFieldArray` from React Hook Form adds and removes rows; each row's fields use an index path:

```tsx
// app/features/invoices/invoice-lines.tsx
import { FieldInput, FormField, useFieldArray, useFormContext } from 'kitr/forms'

type Lines = { lines: { description: string; quantity: string }[] }

export function InvoiceLines() {
  const form = useFormContext<Lines>()
  const lines = useFieldArray({ control: form.control, name: 'lines' })
  return (
    <fieldset>
      <legend>Lines</legend>
      {lines.fields.map((line, index) => (
        <div key={line.id}>
          <FormField name={`lines.${index}.description`} label="Description">
            <FieldInput />
          </FormField>
          <FormField name={`lines.${index}.quantity`} label="Quantity">
            <FieldInput inputMode="numeric" />
          </FormField>
          <button type="button" onClick={() => lines.remove(index)}>
            Remove
          </button>
        </div>
      ))}
      <button type="button" onClick={() => lines.append({ description: '', quantity: '1' })}>
        Add line
      </button>
    </fieldset>
  )
}
```

Use `line.id` as the key, not `index`. A server error for `lines.1.quantity` lands under the second row's quantity input.

## Watch a field

To show or hide part of the form based on a value, read it with `form.watch`:

```tsx
// app/features/invoices/delivery-fields.tsx
import { FieldInput, FormField, useFormContext } from 'kitr/forms'

export function DeliveryFields() {
  const form = useFormContext<{ sendNow: boolean; ccEmail: string }>()
  const sendNow = form.watch('sendNow')
  if (!sendNow) return null
  return (
    <FormField name="ccEmail" label="Copy to" description="Grace in finance gets a copy.">
      <FieldInput type="email" />
    </FormField>
  )
}
```

The component re-renders when `sendNow` changes. Validation of a hidden field is up to the schema: make `ccEmail` optional, or use a zod `discriminatedUnion`.

## Submit without the Form component

When a submit does not go through `<Form>`, for example a "Mark as paid" button that saves one field, call `applyServerErrors` yourself. It puts the error on the form the same way `<Form>` does and returns `true` when the error was a `VALIDATION` error:

```tsx
// app/features/invoices/mark-paid.tsx
import { applyServerErrors, useForm } from 'kitr/forms'

export function MarkPaid({ save }: { save: (paidOn: string) => Promise<void> }) {
  const form = useForm({ defaultValues: { paidOn: '' } })
  const onClick = async () => {
    try {
      await save(form.getValues('paidOn'))
    } catch (error) {
      const isValidation = applyServerErrors(form, error)
      // => true for KitrError.validation(...), false for anything else
      if (!isValidation) console.error(error)
    }
  }
  return (
    <>
      <input type="date" {...form.register('paidOn')} />
      <button type="button" onClick={onClick}>Mark as paid</button>
      <p role="alert">{form.formState.errors.paidOn?.message}</p>
    </>
  )
}
```

`applyServerErrors` accepts a `KitrError`, the plain JSON shape a server sent (`{ code, message, status, fieldErrors }`) or any other thrown value. Anything that is not a field error ends up on `root.server`.

## Style fields

The components are headless. `<FormField>` marks its parts with `data-kitr` attributes so you can style them from CSS or with [Tailwind](/packages/tailwind) arbitrary variants:

| Attribute | Element |
| --- | --- |
| `data-kitr="field"` | The wrapper `<div>`. Has `data-invalid` when the field has an error. |
| `data-kitr="label"` | The `<label>`. |
| `data-kitr="description"` | The description `<p>`. |
| `data-kitr="field-error"` | The error `<p>`, which also has `role="alert"`. |

```tsx
<FormField
  name="amount"
  label="Amount (USD)"
  className="grid gap-1.5 [&_[data-kitr=field-error]]:text-sm [&_[data-kitr=field-error]]:text-destructive"
>
  <FieldInput />
</FormField>
```

For a finished look, copy the styled components into your app:

```sh
kitr ui add form
```

This writes `app/components/ui/form.tsx` (plus `button`, `input` and `label` if they are missing). It exports `Form`, a spaced `FormField`, a `FieldInput` built on your `Input`, a `FormMessage` that shows the root error, and a `SubmitButton` built on your `Button`. Import from `#components/ui/form` instead of `kitr/forms`; the file is yours to edit.

## Make forms accessible

`<FormField>` and `useFieldProps()` produce this markup for a field with a description and a failed check (the ids come from React's `useId`):

```html
<div data-kitr="field" data-invalid="">
  <label for="_r_2_" data-kitr="label">Due on</label>
  <input id="_r_2_" aria-describedby="_r_2_-description _r_2_-error" type="date" name="dueOn" aria-invalid="true">
  <p id="_r_2_-description" data-kitr="description">Customers see this date on the invoice.</p>
  <p id="_r_2_-error" role="alert" data-kitr="field-error">Pick a due date</p>
</div>
```

- Clicking the label focuses the input, because the ids match.
- A screen reader reads the description and the error with the input, through `aria-describedby`.
- The error is announced when it appears, through `role="alert"`.
- `<Form>` sets `noValidate` on the `<form>`, so the browser's own bubbles never compete with these messages.

Give the `<form>` an accessible name (`aria-label="New invoice"`) when the page has more than one.

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:form <name>` | Writes `app/components/forms/<name>_form.tsx`: a zod schema, its type and a form component using the styled `#components/ui/form`. |
| `kitr ui add form` | Copies the styled form components into `app/components/ui/form.tsx`. |
| `kitr eject stub form` | Copies the `make:form` template to `stubs/form.ts` so you can change what it generates. |

```sh
kitr make:form invoice
```

writes:

```tsx
// app/components/forms/invoice_form.tsx
import { useSchemaForm } from 'kitr/forms'
import { z } from 'zod'
import { FieldInput, Form, FormField, FormMessage, SubmitButton } from '#components/ui/form'

export const invoiceSchema = z.object({
  name: z.string().min(2, 'Name must be at least 2 characters'),
})
export type InvoiceValues = z.infer<typeof invoiceSchema>

export function InvoiceForm({ defaultValues, onSubmit }: { defaultValues?: Partial<InvoiceValues>; onSubmit: (values: InvoiceValues) => Promise<unknown> }) {
  const form = useSchemaForm(invoiceSchema, { defaultValues: { name: '', ...defaultValues } })
  return (
    <Form form={form} onSubmit={onSubmit} className="grid gap-4">
      <FormMessage />
      <FormField name="name" label="Name">
        <FieldInput autoComplete="off" />
      </FormField>
      <SubmitButton>Save</SubmitButton>
    </Form>
  )
}
```

The generated file needs `kitr ui add form` first, which the `app` and `fullstack` kits have already run. `kitr doctor` warns when a file under `app/` imports `react-hook-form` directly instead of `kitr/forms`.

## Errors

These are the errors a form shows and where each one appears. The codes are `KitrError` codes, the error shape every kitr data source produces.

| Code | When | What to do |
| --- | --- | --- |
| `VALIDATION` | The server rejected the input (HTTP 422). Messages land on fields; unknown fields and `_root` go to `useRootError()`. | Nothing; the user fixes the fields. Make sure the server's field names match the form's. |
| `UNAUTHORIZED` | The session expired mid-form (401). The message goes to `useRootError()`. | Send the user to sign in from `onError`. |
| `CONFLICT` | Another user changed the record (409). | Reload the record and ask the user to try again. |
| `NETWORK` | The request never reached the server. Root error: "Network request failed". | Keep the values; let the user resubmit. |
| `INTERNAL` | The server crashed (500). In production the root error is "Internal server error". | Read the server log. |
| none | `useFieldProps()` was called outside `<FormField>`: `[kitr/forms] useFieldProps() must be used inside <FormField>.` | Move the input inside a `<FormField>`, or use the render-function child. |

## Testing

Forms run in a DOM test without an app, a router or a server. Render the component, type into it and submit. To test server errors, make the submit function reject with the error the server would send.

```tsx
// app/features/invoices/new-invoice-form.test.tsx
import { fireEvent, render, screen, waitFor } from '@testing-library/react'
import { KitrError } from 'kitr/app'
import { describe, expect, it, vi } from 'vitest'
import { NewInvoiceForm } from './new-invoice-form'

function fill(email: string, amount: string, dueOn: string) {
  fireEvent.change(screen.getByLabelText('Customer email'), { target: { value: email } })
  fireEvent.change(screen.getByLabelText('Amount (USD)'), { target: { value: amount } })
  fireEvent.change(screen.getByLabelText('Due on'), { target: { value: dueOn } })
  fireEvent.submit(screen.getByRole('form', { name: 'New invoice' }))
}

describe('NewInvoiceForm', () => {
  it('shows schema errors without calling the server', async () => {
    const onCreate = vi.fn()
    render(<NewInvoiceForm onCreate={onCreate} />)
    fill('grace', '0', '')
    expect(await screen.findByText('Enter the customer’s email')).toBeTruthy()
    expect(screen.getByText('Amount must be more than zero')).toBeTruthy()
    expect(screen.getByLabelText('Customer email').getAttribute('aria-invalid')).toBe('true')
    expect(onCreate).not.toHaveBeenCalled()
  })

  it('submits typed values and resets', async () => {
    const onCreate = vi.fn().mockResolvedValue({ id: 'inv_1042' })
    render(<NewInvoiceForm onCreate={onCreate} />)
    fill('grace@acme.com', '120', '2026-12-01')
    await waitFor(() =>
      expect(onCreate).toHaveBeenCalledWith({
        customerEmail: 'grace@acme.com',
        amount: 120,
        dueOn: '2026-12-01',
      }),
    )
    await waitFor(() =>
      expect((screen.getByLabelText('Customer email') as HTMLInputElement).value).toBe(''),
    )
  })

  it('puts server errors under the right field and the rest at the top', async () => {
    const onCreate = vi
      .fn()
      .mockRejectedValueOnce(KitrError.validation({ customerEmail: ['No customer with this email'] }))
      .mockRejectedValueOnce(new KitrError('CONFLICT', 'Invoice ACME-1042 already exists'))
    render(<NewInvoiceForm onCreate={onCreate} />)
    fill('linus@acme.com', '80', '2026-12-01')
    expect(await screen.findByText('No customer with this email')).toBeTruthy()
    fireEvent.submit(screen.getByRole('form', { name: 'New invoice' }))
    expect(await screen.findByText('Invoice ACME-1042 already exists')).toBeTruthy()
  })
})
```

`onCreate` receives the schema's output, so the test checks for the number `120`. Run the file with `pnpm test`. A form that calls `useKitrMutation` needs the query client: render it with `renderWithKitr` from [testing](/packages/testing) instead of `render`.

## Next steps

- [API reference](/packages/forms/api): every export with its signature.
- [React Hook Form docs](https://react-hook-form.com/docs): everything there works as written, imported from `kitr/forms`. Its own `<Form>` is exported as `RhfForm`.
- [Server actions](/packages/actions): the server half of a form, with the same error shape.
- [Query](/packages/query): mutations, cache effects and `mutateAsync`.
- [Tailwind](/packages/tailwind): style fields with the `data-kitr` attributes.


# HTTP client API

Source: https://kitr.dev/packages/http/api

`kitr/http` re-exports everything from `ky` and adds the following.

## createHttpClient

```ts
function createHttpClient(options?: HttpClientOptions): KyInstance
```

The provider calls this with `config/http.ts` and binds the result as `http` in the container. Call it yourself to talk to a second API.

| Option | Type | Description |
| --- | --- | --- |
| `baseUrl` | `string` | Prefix for relative paths. |
| `getToken` | `() => string \| null \| Promise<...>` | Called before every request; the result is sent as `Authorization: Bearer <token>`. |
| `refresh` | `() => Promise<boolean>` | Called once on a `401`. Return `true` to retry with a fresh token. |
| `onUnauthorized` | `(error: KitrError) => void` | Called when a `401` can't be recovered. |
| `authHeader` | `string` | Header for the token. Default `Authorization` with a `Bearer ` prefix. |
| ...ky options | | Any other [ky option](https://github.com/sindresorhus/ky#options) except `prefixUrl`. |

GET, PUT, HEAD, DELETE, OPTIONS and TRACE requests retry up to twice when ky's defaults allow it (network failures, timeouts, `429` and `5xx` responses).

## httpQuery

```ts
function httpQuery<TInput = void, TOutput = unknown>(
  client: KyInstance,
  options: {
    path: string | ((input: TInput) => string)
    key: (input: TInput) => QueryKey
    searchParams?: (input: TInput) => Record<string, string | number | boolean | undefined>
    schema?: StandardSchemaV1<unknown, TOutput>
    options?: ky.Options
    staleTime?: number
  },
): QueryContract<TInput, TOutput>
```

A `GET` endpoint as a query contract. Pass it to `defineQuery`. `undefined` search params are dropped.

## httpMutation

```ts
function httpMutation<TInput = void, TOutput = unknown>(
  client: KyInstance,
  options: {
    method?: 'get' | 'post' | 'put' | 'patch' | 'delete' // default 'post'
    path: string | ((input: TInput) => string)
    body?: (input: TInput) => unknown                     // default: the input
    schema?: StandardSchemaV1<unknown, TOutput>
    effects?: CacheEffect | ((result: TOutput, input: TInput) => CacheEffect)
    options?: ky.Options
  },
): MutationContract<TInput, TOutput>
```

An endpoint that changes data, as a mutation contract. Pass it to `defineMutation`.

## normaliseHttpError

```ts
function normaliseHttpError(error: unknown): Promise<KitrError>
```

Turns a ky `HTTPError`, or anything else, into a `KitrError`. The client already applies it; use it when calling `fetch` yourself.

## defineConfig

```ts
defineConfig(config: HttpClientOptions): HttpClientOptions
```


# HTTP client

Source: https://kitr.dev/packages/http

If your app talks to a backend that already exists, such as a Laravel, Rails, Adonis or Go API, you need a client that adds the user's login token to every request, tries once to refresh it when it expires, and turns every kind of failure into one predictable error. `kitr/http` is that client.

It is [ky](https://github.com/sindresorhus/ky#readme), re-exported, plus `createHttpClient`, which adds the token, refresh, CSRF and error handling, and two helpers, `httpQuery` and `httpMutation`, that turn endpoints into [Query](/packages/query) contracts. The app gets one client, bound in the container as `http`.

It runs in the browser, and on the server when a page renders. When the API is part of this app, use [API](/packages/api) instead: its client is typed straight from your routes.

This guide follows Acme's order screen at `app.acme.com` talking to an API at `api.acme.com`.

## When to use it

Use `kitr/http` when the API lives outside this app: a separate backend, a vendor's REST API, a service another team owns. You describe each endpoint once with `httpQuery` or `httpMutation`, and components read it through queries like any other source.

Use [API](/packages/api) when you write the endpoints in this app's `server/` folder, because its client gets the routes, inputs and outputs from your code with no hand-written types. Use [Actions](/packages/actions) for a server function you call from a form or button without designing a URL.

## Install

```sh
kitr add http
```

What `kitr add` does:

- Adds [Query](/packages/query) first if the project does not have it, because `http` requires it.
- Installs `@kitr/http` and `ky`.
- Adds `() => import('@kitr/http/provider')` to `providers` in `kitrrc.ts`.
- Adds `@kitr/http` to `packages` in `kitrrc.ts`.
- Adds `VITE_API_URL: e.url({ default: 'http://localhost:3333' })` to the `public` block of `createEnv` in `app/env.ts`.
- Adds `VITE_API_URL=http://localhost:3333` to `.env.example`, and to `.env` when that file exists.
- Writes `config/http.ts` (shown under [Configure](#configure)).
- Adds a `## kitr: http` section to `AGENTS.md`: the client is `app.container.use('http')`, endpoints are wrapped with `httpQuery`/`httpMutation`, and errors are already `KitrError`.

`kitr add http` asks no questions. The `app`, `fullstack`, `saas`, `desktop` and `mobile` kits include it. To preview the changes without writing them:

```sh
kitr add http --dry-run
```

`kitr remove http` removes the provider, the `packages` entry, the `ky` and `@kitr/http` dependencies, the `AGENTS.md` section and `config/http.ts`. It leaves `VITE_API_URL` in `app/env.ts` and `.env.example`, and lists the files that still import `kitr/http`.

## Configure

`kitr add http` writes this file:

```ts
// config/http.ts
import { defineConfig } from 'kitr/http'
import { env } from '#app/env'

export default defineConfig({
  baseUrl: env.VITE_API_URL,
  // getToken: () => auth.getToken(), refresh: () => auth.refresh(),
})
```

| Option | Default | Description |
| --- | --- | --- |
| `baseUrl` | none | Prefix for every relative path. `http.get('orders')` with `baseUrl: 'https://api.acme.com/v1'` requests `https://api.acme.com/v1/orders`. |
| `getToken` | none | Called before every request. Return a token (or a promise of one) to send it; return `null` or `undefined` to send none. |
| `refresh` | none | Called once when a response is `401`. Return `true` when a new token is ready; the request then retries once with it. |
| `onUnauthorized` | none | Called with the `KitrError` whenever a request finally fails with `401`, for example to send the user to sign in. |
| `authHeader` | `'Authorization'` | Header that carries the token. With the default the value is `Bearer <token>`; any other header gets the raw token. |
| `retry` | `{ limit: 2, methods: ['get', 'put', 'head', 'delete', 'options', 'trace'] }` | ky's retry rule. `POST` and `PATCH` are never retried, so a write is never sent twice. |
| `timeout` | `10_000` | ky's per-request timeout in milliseconds, or `false` for none. |
| `hooks` | `{}` | ky hooks. Yours run after kitr's own `beforeRequest`, `afterResponse` and `beforeError` hooks. |
| `headers`, `credentials`, `fetch`, ... | ky's defaults | Every other [ky option](https://github.com/sindresorhus/ky#options) except `prefixUrl` passes through unchanged. |

| Variable | Used for |
| --- | --- |
| `VITE_API_URL` | The API's base URL, read through `env.VITE_API_URL`. Public, so it ships to the browser. Defaults to `http://localhost:3333`. |

To point production at the real API, set the variable where the app is built:

```sh
VITE_API_URL=https://api.acme.com/v1 pnpm build
```

Because `config/http.ts` is a module, you can compute options in it. This config sends cookies to the API on another origin and adds a header that names the client:

```ts
// config/http.ts
import { defineConfig } from 'kitr/http'
import { env } from '#app/env'

export default defineConfig({
  baseUrl: env.VITE_API_URL,
  credentials: 'include',
  headers: { 'x-acme-client': 'web' },
  timeout: 15_000,
})
```

## Load your first endpoint

Describe the endpoint once in the feature's `queries.ts`. `httpQuery` turns it into a query contract, and `defineQuery` turns that into something components and loaders use:

```ts
// app/features/orders/queries.ts
import { app } from '#app/app'
import { createKeys } from 'kitr/app'
import { httpQuery } from 'kitr/http'
import { defineQuery } from 'kitr/query'

export interface Order {
  id: string
  customer: string
  total: number
  status: 'open' | 'paid' | 'shipped'
}

const http = app.container.use('http')
export const orderKeys = createKeys('orders')

export const ordersQuery = defineQuery(
  httpQuery<void, Order[]>(http, {
    path: 'orders',
    key: () => orderKeys.list(),
  }),
)
```

Then show it on a page:

```tsx
// app/routes/orders.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useSuspenseQuery } from 'kitr/query'
import { ordersQuery } from '#app/features/orders/queries'

export const Route = createFileRoute('/orders')({
  loader: ({ context }) => context.queryClient.ensureQueryData(ordersQuery.options()),
  component: OrdersPage,
})

function OrdersPage() {
  const { data: orders } = useSuspenseQuery(ordersQuery.options())
  return (
    <ul>
      {orders.map((order) => (
        <li key={order.id}>
          {order.customer}: ${order.total}
        </li>
      ))}
    </ul>
  )
}
```

Open `/orders`. The loader calls `GET http://localhost:3333/orders`, and the page lists what the API returns, for example `Ada: $120` and `Grace: $80`. If the API is not running, the route's error component shows the `KitrError` instead.

## Read the client

The provider binds one client as `http` in the container. It is a normal ky instance, so every ky method works on it.

Outside components, such as in `queries.ts` or a loader, read it from the app:

```ts
// app/features/invoices/download.ts
import { app } from '#app/app'

const http = app.container.use('http')

export async function downloadInvoice(id: string) {
  return http.get(`invoices/${id}/pdf`).blob()
}
```

In a component, read it with `useService` from `kitr/react`:

```tsx
// app/features/invoices/download-button.tsx
import { useService } from 'kitr/react'

export function DownloadButton({ id }: { id: string }) {
  const http = useService('http')
  const download = async () => {
    const pdf = await http.get(`invoices/${id}/pdf`).blob()
    window.open(URL.createObjectURL(pdf))
  }
  return (
    <button type="button" onClick={download}>
      Download PDF
    </button>
  )
}
```

Prefer `httpQuery` for anything a screen shows: the cache, loading states and refreshes come for free. Use the client directly for one-off calls such as a download.

## Call an endpoint directly

The client has a method per HTTP verb. Each returns a response promise with `.json()`, `.text()`, `.blob()` and `.arrayBuffer()`:

```ts
// app/features/orders/api.ts
import { app } from '#app/app'
import type { Order } from './queries'

const http = app.container.use('http')

const orders = await http.get('orders', { searchParams: { status: 'open', page: 2 } }).json<Order[]>()
// GET https://api.acme.com/v1/orders?status=open&page=2

const created = await http.post('orders', { json: { customer: 'Linus', total: 45 } }).json<Order>()
// => { id: 'ord_3', customer: 'Linus', total: 45, status: 'open' }

await http.delete(`orders/${created.id}`)
```

A leading slash makes no difference: `http.get('/orders')` and `http.get('orders')` both request `<baseUrl>/orders`. An absolute URL such as `https://billing.acme.com/rates` ignores `baseUrl`.

For a client with extra defaults, call ky's `extend`. It keeps the token, refresh and error handling:

```ts
// app/features/billing/client.ts
import { app } from '#app/app'

export const billing = app.container.use('http').extend({
  headers: { 'x-acme-team': 'billing' },
  timeout: 30_000,
})
```

## Turn an endpoint into a query

`httpQuery(client, options)` returns a query contract that sends a `GET`. Pass it to `defineQuery`:

```ts
// app/features/orders/queries.ts
import { app } from '#app/app'
import { createKeys } from 'kitr/app'
import { httpQuery } from 'kitr/http'
import { defineQuery } from 'kitr/query'
import type { Order } from './types'

const http = app.container.use('http')
export const orderKeys = createKeys('orders')

export const orderQuery = defineQuery(
  httpQuery<string, Order>(http, {
    path: (id) => `orders/${id}`,
    key: (id) => orderKeys.detail(id),
  }),
)

export const ordersQuery = defineQuery(
  httpQuery<{ status?: Order['status']; page: number }, Order[]>(http, {
    path: 'orders',
    key: (filters) => orderKeys.list(filters),
    searchParams: ({ status, page }) => ({ status, page }),
    staleTime: 10_000,
  }),
)
```

| Option | Default | Description |
| --- | --- | --- |
| `path` | required | A path relative to `baseUrl`, or a function of the input that returns one. |
| `key` | required | The cache key for an input. Include every input that changes the result. |
| `searchParams` | none | A function of the input that returns query string values. `undefined` values are left out, so `{ status: undefined, page: 1 }` sends `?page=1`. |
| `schema` | none | A [Standard Schema](https://standardschema.dev) that validates the response and types the result. |
| `options` | `{}` | ky options for this request only, such as `headers` or `timeout`. |
| `staleTime` | the config's | How long this query's data stays fresh, in milliseconds. |

The query passes TanStack's abort signal to ky, so leaving the page cancels the request. The contract's `source` is `'http'`, which devtools shows.

## Validate the response

An API you don't control can change shape. Give `httpQuery` or `httpMutation` a `schema` from zod, valibot or any other Standard Schema library, and a response that fails it becomes a `VALIDATION` error instead of a crash three components later. The schema also types the result, so you can drop the generic:

```ts
// app/features/invoices/queries.ts
import { app } from '#app/app'
import { createKeys } from 'kitr/app'
import { httpQuery } from 'kitr/http'
import { defineQuery } from 'kitr/query'
import { z } from 'zod'

const http = app.container.use('http')
export const invoiceKeys = createKeys('invoices')

const invoice = z.object({
  id: z.string(),
  orderId: z.string(),
  total: z.number(),
  paidAt: z.string().nullable(),
})

export const invoicesQuery = defineQuery(
  httpQuery(http, {
    path: 'invoices',
    key: () => invoiceKeys.list(),
    schema: z.array(invoice),
  }),
)
```

When the API sends `{ "total": "80.00" }` where a number is expected, the query fails with:

```ts
// => KitrError { code: 'VALIDATION', status: 422, message: 'Validation failed', fieldErrors: { '0.total': ['Invalid input: expected number, received string'] } }
```

The key is the path to the bad value (`0.total`: the first invoice's `total`). The message comes from your schema library; this one is zod 4's.

## Turn an endpoint into a mutation

`httpMutation(client, options)` returns a mutation contract. Pass it to `defineMutation` and run it with `useKitrMutation`. Declare `effects` so every screen showing the changed data updates:

```ts
// app/features/orders/queries.ts
import { app } from '#app/app'
import { httpMutation } from 'kitr/http'
import { defineMutation } from 'kitr/query'
import { orderKeys } from './keys'
import type { Order } from './types'

const http = app.container.use('http')

export const createOrder = defineMutation(
  httpMutation<{ customer: string; total: number }, Order>(http, {
    path: 'orders',
    effects: { invalidate: [orderKeys.lists()] },
  }),
)

export const shipOrder = defineMutation(
  httpMutation<{ id: string; carrier: string }, Order>(http, {
    method: 'post',
    path: (input) => `orders/${input.id}/ship`,
    body: (input) => ({ carrier: input.carrier }),
    effects: (order) => ({
      set: [{ key: orderKeys.detail(order.id), data: order }],
      invalidate: [orderKeys.lists()],
    }),
  }),
)
```

```tsx
// app/features/orders/ship-button.tsx
import { useKitrMutation } from 'kitr/query'
import { shipOrder } from './queries'

export function ShipButton({ id }: { id: string }) {
  const ship = useKitrMutation(shipOrder)
  return (
    <button type="button" disabled={ship.isPending} onClick={() => ship.mutate({ id, carrier: 'UPS' })}>
      Ship
    </button>
  )
}
```

| Option | Default | Description |
| --- | --- | --- |
| `method` | `'post'` | One of `'get'`, `'post'`, `'put'`, `'patch'`, `'delete'`. |
| `path` | required | A path, or a function of the input that returns one. |
| `body` | the input | A function that builds the JSON body from the input. Without it, the whole input is the body, except for `get` and `delete`, which send none. |
| `schema` | none | A Standard Schema that validates the response and types the result. |
| `effects` | none | Cache effects after success: an object, or a function of `(result, input)`. See [Query](/packages/query). |
| `options` | `{}` | ky options for this request only. |

## Delete and update records

`delete` sends no body by default, and a `204 No Content` response resolves to `undefined`, so the result type is `void`:

```ts
// app/features/projects/queries.ts
import { app } from '#app/app'
import { createKeys } from 'kitr/app'
import { httpMutation } from 'kitr/http'
import { defineMutation } from 'kitr/query'

const http = app.container.use('http')
export const projectKeys = createKeys('projects')

export const deleteProject = defineMutation(
  httpMutation<{ id: string }, void>(http, {
    method: 'delete',
    path: ({ id }) => `projects/${id}`,
    effects: (_result, { id }) => ({
      remove: [projectKeys.detail(id)],
      invalidate: [projectKeys.lists()],
    }),
  }),
)

export const renameProject = defineMutation(
  httpMutation<{ id: string; name: string }, { id: string; name: string }>(http, {
    method: 'patch',
    path: ({ id }) => `projects/${id}`,
    body: ({ name }) => ({ name }),
    effects: (project) => ({ set: [{ key: projectKeys.detail(project.id), data: project }] }),
  }),
)
```

`renameProject` sends `PATCH /projects/prj_1` with the body `{"name":"Website"}`; the `id` stays in the URL because `body` leaves it out.

## Upload a file

`httpMutation` always sends JSON. For a file, call the client with a `FormData` body and let the browser set the multipart headers:

```ts
// app/features/invoices/import.ts
import { app } from '#app/app'
import { defineMutation } from 'kitr/query'
import { invoiceKeys } from './queries'

const http = app.container.use('http')

export const importInvoices = defineMutation({
  mutate: async (file: File) => {
    const form = new FormData()
    form.append('file', file)
    return http.post('invoices/import', { body: form, timeout: 60_000 }).json<{ imported: number }>()
  },
  effects: { invalidate: [invoiceKeys.lists()] },
})
// => { imported: 42 }
```

Don't set `content-type` yourself for `FormData`: the browser adds the boundary the server needs to parse the body. For uploads to your own server with progress and size limits, see [Uploads](/packages/uploads).

## Send the login token

`getToken` runs before every request. When it returns a token, the client sends `Authorization: Bearer <token>`. With [Auth](/packages/auth)'s token adapter, keep the adapter in its own module and point the client at it:

```ts
// app/auth/adapter.ts
import { localStorageTokens, tokenAdapter } from 'kitr/auth'
import { env } from '#app/env'

export const authAdapter = tokenAdapter<{ id: string; email: string }>({
  storage: localStorageTokens('acme:token'),
  refreshStorage: localStorageTokens('acme:refresh'),
  fetchUser: async (token) => {
    const res = await fetch(`${env.VITE_API_URL}/me`, { headers: { authorization: `Bearer ${token}` } })
    return res.ok ? res.json() : null
  },
  refresh: async (refreshToken) => {
    const res = await fetch(`${env.VITE_API_URL}/auth/refresh`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ refreshToken }),
    })
    return res.ok ? res.json() : null
  },
})
```

```ts
// config/http.ts
import { defineConfig } from 'kitr/http'
import { authAdapter } from '#app/auth/adapter'
import { env } from '#app/env'

export default defineConfig({
  baseUrl: env.VITE_API_URL,
  getToken: () => authAdapter.getToken?.(),
  refresh: async () => (await authAdapter.refresh?.()) ?? false,
  onUnauthorized: () => window.location.assign('/sign-in'),
})
```

Components never touch the token. When Ada signs in, the adapter stores her token, and the next request carries it.

An API that expects a key in its own header gets the raw token. This config sends `x-api-key: <token>` and no `Authorization` header:

```ts
// config/http.ts
import { defineConfig } from 'kitr/http'
import { env } from '#app/env'

export default defineConfig({
  baseUrl: env.VITE_API_URL,
  authHeader: 'x-api-key',
  getToken: () => localStorage.getItem('acme:api-key'),
})
```

> **Warning**
> `VITE_` variables are compiled into the browser bundle, where anyone can read them. Never put a secret API key in one. Fetch per-user tokens at sign-in instead.

## Refresh an expired token

When a response is `401` and `refresh` is set, the client calls `refresh()` once. If it returns `true`, the client reads the token again with `getToken()` and retries the request once, marked with an `x-kitr-retried: 1` header. If it returns `false`, or the retry is also `401`, the request fails with an `UNAUTHORIZED` error and `onUnauthorized` runs.

Several requests that fail at the same moment share one `refresh()` call. When Grace's dashboard loads orders, invoices and projects together after her token expired, the client refreshes once and retries all three with the new token.

`onUnauthorized` runs for every request that ends in `401`, with or without `refresh`. Use it to sign the user out or send them to the sign-in page, not to show a message per request:

```ts
// config/http.ts
import { defineConfig } from 'kitr/http'
import { env } from '#app/env'

export default defineConfig({
  baseUrl: env.VITE_API_URL,
  onUnauthorized: (error) => {
    console.warn('Session ended:', error.message)
    window.location.assign(`/sign-in?next=${encodeURIComponent(window.location.pathname)}`)
  },
})
```

## Send the CSRF token

On every request except `GET`, `HEAD` and `OPTIONS`, the client reads the `kitr-csrf` cookie and sends its value as the `x-csrf-token` header. That is the double-submit check of [Shield](/packages/shield), so writes to a same-site kitr server pass its CSRF check with no code. A request that already has an `x-csrf-token` header keeps it. On the server there is no `document`, so no header is added.

## Retry and time out

Idempotent requests (`GET`, `PUT`, `HEAD`, `DELETE`, `OPTIONS`, `TRACE`) retry up to twice on ky's retryable statuses, such as `408`, `429`, `500`, `502`, `503` and `504`, and on network errors, with ky's backoff between attempts. `POST` and `PATCH` are never retried, because sending a payment or an order twice is worse than showing an error.

Queries add their own retries on top: [Query](/packages/query) retries failed queries twice unless the status is 4xx. For a screen that must fail fast, turn off one layer:

```ts
// config/http.ts
import { defineConfig } from 'kitr/http'
import { env } from '#app/env'

export default defineConfig({
  baseUrl: env.VITE_API_URL,
  retry: 0, // Query's retries are enough
  timeout: 5_000,
})
```

For one slow endpoint, pass `options` to the contract instead of changing every request:

```ts
// app/features/reports/queries.ts
import { app } from '#app/app'
import { httpQuery } from 'kitr/http'
import { defineQuery } from 'kitr/query'

const http = app.container.use('http')

export const yearlyReportQuery = defineQuery(
  httpQuery<number, { year: number; revenue: number }>(http, {
    path: (year) => `reports/${year}`,
    key: (year) => ['reports', year],
    options: { timeout: 60_000, retry: 0 },
  }),
)
```

## Add hooks

ky [hooks](https://github.com/sindresorhus/ky#hooks) run around every request. Pass them in `config/http.ts`; yours run after kitr's, so `beforeRequest` sees the token already set and `beforeError` receives the normalised `KitrError`:

```ts
// config/http.ts
import { defineConfig } from 'kitr/http'
import { env } from '#app/env'

export default defineConfig({
  baseUrl: env.VITE_API_URL,
  hooks: {
    beforeRequest: [
      ({ request }) => {
        request.headers.set('x-request-id', crypto.randomUUID())
      },
    ],
    afterResponse: [
      ({ response }) => {
        const remaining = response.headers.get('x-ratelimit-remaining')
        if (remaining === '0') console.warn('Acme API rate limit reached')
      },
    ],
  },
})
```

## Handle errors

Every failure becomes a `KitrError` with `code`, `status`, `message` and, when the API sends them, `fieldErrors` and `data`. Components, forms and queries check `code`, never the raw response:

```ts
// app/features/orders/place-order.ts
import { app } from '#app/app'
import { isKitrError } from 'kitr/app'

const http = app.container.use('http')

try {
  await http.post('orders', { json: { customer: 'Ada', total: -5 } })
} catch (error) {
  if (isKitrError(error) && error.code === 'VALIDATION') console.log(error.fieldErrors)
  // => { total: ['Must be positive'] }
}
```

The client reads the error body in this order:

| The API responds with | The `KitrError` has |
| --- | --- |
| kitr's own shape `{ code, message, status, fieldErrors? }` | Those fields as-is. |
| `{ errors: [{ field, message }] }` (Adonis, VineJS) | `fieldErrors` keyed by `field`, or `path`; entries without either go under `_root`. |
| `{ message: '...' }` | That message. |
| `{ error: { message: '...' } }` or `{ error: '...' }` | That message. |
| No JSON body, such as an HTML error page | The status's code and a message from it, such as `'Not found'`. |

The full parsed body is kept in `error.data`. For example, a `409` with `{ "message": "Invoice already paid" }` becomes:

```ts
// => KitrError { code: 'CONFLICT', status: 409, message: 'Invoice already paid', data: { message: 'Invoice already paid' } }
```

A `422` whose `fieldErrors` reach a [Forms](/packages/forms) `<Form>` shows each message under its input, with no code in the component.

## Errors

| Code | When | What to do |
| --- | --- | --- |
| `BAD_REQUEST` | `400`, or any 4xx not listed below. | Fix the request; the message usually says what is wrong. |
| `UNAUTHORIZED` | `401` after `refresh` failed or was not set. `onUnauthorized` runs. | Sign the user in again. |
| `FORBIDDEN` | `403`. | Hide the action, or ask the API owner for access. |
| `NOT_FOUND` | `404`. | Show a not-found state; the record was deleted or the path is wrong. |
| `TIMEOUT` | `408` from the server. | Retry later. |
| `CONFLICT` | `409`. | Reload the record and let the user decide. |
| `PAYLOAD_TOO_LARGE` | `413`. | Send a smaller body or file. |
| `VALIDATION` | `422`, or a response that fails the contract's `schema`. | Show `fieldErrors` next to the inputs; for a schema failure, update the schema or the API. |
| `RATE_LIMITED` | `429`. | Back off; ky already retried idempotent requests. |
| `INTERNAL` | `500` or any other 5xx; also a network failure or a client-side timeout. | Show a retry button. The message names the cause, such as `Request timed out: GET https://api.acme.com/v1/orders`. |
| `UNAVAILABLE` | `503`. | Show a maintenance notice and retry later. |

`normaliseHttpError(error)` performs this mapping on any error, if you call ky outside the client:

```ts
// app/lib/errors.ts
import { normaliseHttpError } from 'kitr/http'

export async function describeError(error: unknown) {
  const kitrError = await normaliseHttpError(error)
  return `${kitrError.code} (${kitrError.status}): ${kitrError.message}`
}
// describeError(new TypeError('Failed to fetch')) => 'NETWORK (0): Network request failed'
```

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:queries <name>` | Writes `app/features/<name>/queries.ts` with keys, a list query, a detail query and an update mutation over `kitr/http`. |

```sh
kitr make:queries orders
```

It writes `app/features/orders/queries.ts`:

```ts
// app/features/orders/queries.ts
import { createKeys } from 'kitr/app'
import { defineMutation, defineQuery } from 'kitr/query'
import { httpMutation, httpQuery } from 'kitr/http'
import { app } from '#app/app'

const http = app.container.use('http')
export const ordersKeys = createKeys('orders')

export interface Orders {
  id: string
  name: string
}

export const ordersListQuery = defineQuery(
  httpQuery<void, Orders[]>(http, { path: 'orders', key: () => ordersKeys.list() }),
)

export const ordersQuery = defineQuery(
  httpQuery<string, Orders>(http, { path: (id) => `orders/${id}`, key: (id) => ordersKeys.detail(id) }),
)

export const updateOrders = defineMutation(
  httpMutation<Partial<Orders> & { id: string }, Orders>(http, {
    method: 'patch',
    path: (input) => `orders/${input.id}`,
    effects: (result) => ({ set: [{ key: ordersKeys.detail(result.id), data: result }], invalidate: [ordersKeys.lists()] }),
  }),
)
```

Names come from the argument as given, so pass the singular (`kitr make:queries order`) if you want `Order` and `orderQuery`. Pass `--force` to overwrite an existing file. To change the template for your project, run `kitr eject stub queries` and edit `stubs/queries.ts`.

## Testing

`createHttpClient` takes ky's `fetch` option, so a test passes a fake `fetch` and never touches the network. The fake sees the real `Request`, with the URL, headers and body the client built:

```ts
// app/features/orders/queries.test.ts
import { createKeys } from 'kitr/app'
import { createHttpClient, httpMutation, httpQuery } from 'kitr/http'
import { describe, expect, it, vi } from 'vitest'

interface Order {
  id: string
  customer: string
  status: 'open' | 'shipped'
}

const orderKeys = createKeys('orders')

function fakeApi(handler: (request: Request) => Response) {
  const requests: Request[] = []
  const fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
    const request = input instanceof Request ? input : new Request(input, init)
    requests.push(request.clone())
    return handler(request)
  })
  return { fetch: fetch as unknown as typeof globalThis.fetch, requests }
}

describe('orders endpoints', () => {
  it('lists open orders with the token and filters', async () => {
    const api = fakeApi(() => Response.json([{ id: 'ord_1', customer: 'Ada', status: 'open' }]))
    const http = createHttpClient({ baseUrl: 'https://api.acme.com/v1', getToken: () => 'tok_ada', fetch: api.fetch })
    const orders = httpQuery<{ status?: string }, Order[]>(http, {
      path: 'orders',
      key: (filters) => orderKeys.list(filters),
      searchParams: ({ status }) => ({ status }),
    })

    expect(await orders.fetch({ status: 'open' }, {})).toEqual([{ id: 'ord_1', customer: 'Ada', status: 'open' }])
    expect(api.requests[0]!.url).toBe('https://api.acme.com/v1/orders?status=open')
    expect(api.requests[0]!.headers.get('authorization')).toBe('Bearer tok_ada')
  })

  it('turns a 422 into field errors', async () => {
    const api = fakeApi(() =>
      Response.json({ errors: [{ field: 'customer', message: 'Required' }] }, { status: 422 }),
    )
    const http = createHttpClient({ baseUrl: 'https://api.acme.com/v1', fetch: api.fetch })
    const createOrder = httpMutation<{ customer: string }, Order>(http, { path: 'orders' })

    await expect(createOrder.mutate({ customer: '' })).rejects.toMatchObject({
      code: 'VALIDATION',
      status: 422,
      fieldErrors: { customer: ['Required'] },
    })
    expect(await api.requests[0]!.json()).toEqual({ customer: '' })
  })
})
```

To test with the app's own provider and config, boot a test app and pass the fake `fetch` in the `http` config:

```ts
// app/features/orders/provider.test.ts
import { httpProvider } from 'kitr/http'
import { createTestApp } from 'kitr/testing'
import { expect, it } from 'vitest'

it('binds a client with the base URL', async () => {
  const fetch = async (input: RequestInfo | URL) =>
    Response.json({ url: input instanceof Request ? input.url : String(input) })
  const app = await createTestApp({
    providers: [httpProvider],
    config: { http: { baseUrl: 'https://api.acme.com/v1', fetch: fetch as typeof globalThis.fetch } },
  })

  expect(await app.container.use('http').get('teams').json()).toEqual({
    url: 'https://api.acme.com/v1/teams',
  })
})
```

To fake the API for a whole app, in tests and in the browser during development, use [Mocks](/packages/mocks): its handlers answer every request the client makes, with no change to `config/http.ts`.

## Devtools

With [Devtools](/packages/devtools) installed, every request in development is logged to the Log panel under `http`, for example `GET /orders → 200 (84ms)`. The entry carries the full URL, the status and the time in milliseconds. Responses from `400` to `499` log as warnings and `500` and above as errors, so a failing endpoint stands out.

## Next steps

- [API reference](/packages/http/api)
- [ky docs](https://github.com/sindresorhus/ky#readme): every option and method works on the `http` client.
- [Query](/packages/query): caching, mutations and effects for the contracts this package builds.
- [Auth](/packages/auth): sign-in and the token adapter that feeds `getToken` and `refresh`.
- [Mocks](/packages/mocks): fake the API in tests and development.
- [Loading and saving data](/docs/data): how HTTP fits beside API routes, actions and realtime.


# Translations API

Source: https://kitr.dev/packages/i18n/api

Every export of `kitr/i18n`, `kitr/i18n/provider`, read from the published type definitions. The [guide](/packages/i18n) shows them in use.

## kitr/i18n

Re-exports `i18next`, `react-i18next` unchanged, plus the following.

### createI18n

```ts
function createI18n(config: I18nConfig, initialLocale?: string): i18n;
```

Creates an isolated i18next instance from your config, already initialised with react-i18next.
The locale is `initialLocale`, else the detected one when `detect` is on, else `defaultLocale`.

### detectLocale

```ts
function detectLocale(supported: string[], storageKey?: string): string | undefined;
```

In the browser, the saved choice under `storageKey` in localStorage, else the best match for
`navigator.languages`. Returns `undefined` on the server or when nothing matches.

### matchLocale

```ts
function matchLocale(candidates: string | readonly string[], supported: string[]): string | undefined;
```

Pick the best supported locale from an `Accept-Language` header (server) or a language list.

### defineConfig

```ts
const defineConfig: <const C extends I18nConfig>(config: C) => C;
```

Types `config/i18n.ts`. Returns the object you pass, unchanged.

### I18nConfig

```ts
interface I18nConfig extends Omit<InitOptions, 'resources' | 'lng'> {
  /** Every locale's strings, keyed by locale then namespace: `{ en: { common: { hello: 'Hello' } } }`. */
  resources: Record<string, Record<string, Record<string, unknown>>>;
  /** The locale used when nothing better matches, and the fallback for missing keys. */
  defaultLocale: string;
  /** The locales the app supports. Default: the keys of `resources`. */
  locales?: string[];
  /** Detect from `navigator.language` (client) or `Accept-Language` (server). Default true. */
  detect?: boolean;
  /** Query/cookie/storage key for an explicit choice. Default `locale`. */
  storageKey?: string;
}
```

The options in `config/i18n.ts`: your strings per locale, the fallback locale and detection.
Any other i18next init option passes straight through.

### TranslationKeys

```ts
type TranslationKeys<R, Prefix extends string = ''> = {
  [K in keyof R & string]: R[K] extends string ? `${Prefix}${K}` : TranslationKeys<R[K], `${Prefix}${K}.`>;
}[keyof R & string];
```

Keys of a resource bundle as `namespace:key.path` strings, for typed `t()`.

## kitr/i18n/provider

### i18nProvider

```ts
const i18nProvider: KitrProvider;
```

Binds `i18n` from `config/i18n.ts` and wraps the tree in I18nextProvider.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Translations

Source: https://kitr.dev/packages/i18n

Acme's first customers all read English. Then a team in Berlin signs up, and every button, empty state and order total needs to read naturally in German too. `kitr/i18n` moves your interface text into one file per language, picks the visitor's language automatically, and makes a misspelled key a type error instead of a blank on the screen.

It is [react-i18next](https://react.i18next.com) and [i18next](https://www.i18next.com), re-exported unchanged, with a provider and defaults most apps want: an isolated i18next instance per app, the fallback language set to your default locale, no HTML escaping (React already escapes), no Suspense, and locale detection from a saved choice or the browser. It adds `matchLocale()` to pick a language from an `Accept-Language` header and a `TranslationKeys` type for typed key props.

It runs in the browser, inside React. The provider is client-side, and `kitr add i18n` skips a server-only project with a warning. On the server you can still call `createI18n()` or `matchLocale()` directly, to translate an email or choose the language of a server-rendered page. Translating your marketing content in a CMS is a different job; this package is for the strings in your code.

The examples on this page translate Acme's order screens at `app.acme.com` into English and German: the page title, the order count, totals in euros and a welcome line for Ada.

## Install

```sh
kitr add i18n
```

What `kitr add` does:

- Adds `@kitr/i18n`, `i18next` and `react-i18next` to `dependencies` and installs them. Pass `--no-install` to skip the install.
- Adds `() => import('@kitr/i18n/provider')` to `providers` and `'@kitr/i18n'` to `packages` in `kitrrc.ts`. The provider binds `i18n` in the container and wraps your app in react-i18next's `I18nextProvider`.
- Writes `app/locales/en.ts` with a `common` namespace holding `hello` and `save`, unless the file exists.
- Writes `config/i18n.ts`, unless it exists. See [Configure](#configure).
- Adds a `## kitr: i18n` section to `AGENTS.md`: strings live in `app/locales/<lang>.ts`, components call `const { t } = useTranslation()` from `kitr/i18n`, and keys are typed from the English bundle.

It adds no env variables, no scripts and asks no questions. The `site` kit includes i18n with English and German bundles, a language switch, and the visitor's choice in a cookie so server-rendered pages arrive in the right language.

`kitr remove i18n` takes the provider and the package out of `kitrrc.ts`, deletes `config/i18n.ts`, removes the three dependencies and the `AGENTS.md` section, then lists files under `app/` and `config/` that still import `kitr/i18n`. It leaves `app/locales/` in place.

## Configure

`kitr add i18n` writes this file:

```ts
// config/i18n.ts
import { defineConfig } from 'kitr/i18n'
import en from '#app/locales/en'

export default defineConfig({
  resources: { en },
  defaultLocale: 'en',
  defaultNS: 'common',
})
```

| Option | Default | Description |
| --- | --- | --- |
| `resources` | required | Every locale's strings, keyed by locale then namespace: `{ en: { common: { ... } } }`. |
| `defaultLocale` | required | The language used when nothing better matches, and the fallback for any key missing in another language. |
| `locales` | the keys of `resources` | The languages the app supports. A language outside this list is never chosen, even when you call `changeLanguage()` with it. |
| `detect` | `true` | In the browser, choose the language from the saved choice under `storageKey`, then from the browser's languages. `false` always starts in `defaultLocale`. |
| `storageKey` | `'locale'` | The `localStorage` key detection reads for a saved choice. |
| `defaultNS` | i18next's `'translation'` | The namespace `t('save')` looks in when the key names none. Keep it `'common'` to match the generated bundle. |

Any other [i18next option](https://www.i18next.com/overview/configuration-options) passes straight through, and wins over kitr's defaults:

| i18next option | kitr's default | Why |
| --- | --- | --- |
| `fallbackLng` | `defaultLocale` | A German page with a missing key shows the English string, not the key. |
| `supportedLngs` | `locales` | Only languages you ship are chosen. |
| `interpolation.escapeValue` | `false` | React escapes text already; escaping twice shows `&lt;`. |
| `react.useSuspense` | `false` | Bundles are in memory, so there is nothing to wait for. |

Passing `interpolation` replaces kitr's whole object, so include `escapeValue: false` in it when you add other interpolation options. i18n reads no env variables.

## Translate your first string

The generated `app/locales/en.ts` holds one namespace, `common`:

```ts
// app/locales/en.ts
export default {
  common: {
    hello: 'Hello, {{name}}',
    save: 'Save',
  },
} as const
```

In a component, `useTranslation()` from `kitr/i18n` returns `t`, which looks a key up in the current language:

```tsx
// app/features/orders/welcome.tsx
import { useTranslation } from 'kitr/i18n'

export function Welcome({ name }: { name: string }) {
  const { t } = useTranslation()
  return (
    <section>
      <h2>{t('hello', { name })}</h2>
      <button type="submit">{t('save')}</button>
    </section>
  )
}
```

`<Welcome name="Ada" />` renders "Hello, Ada" and a "Save" button. The provider created the i18next instance at startup, so there is nothing to load and nothing to wait for. `as const` on the bundle keeps the exact strings, which [typed keys](#type-your-keys) need.

## Organise strings into namespaces

Each top-level key in a bundle is a namespace. Keep `common` for words used everywhere and give each feature its own:

```ts
// app/locales/en.ts
export default {
  common: {
    hello: 'Hello, {{name}}',
    save: 'Save',
    cancel: 'Cancel',
  },
  orders: {
    title: 'Orders',
    empty: 'No orders yet',
    status: { open: 'Open', paid: 'Paid', refunded: 'Refunded' },
  },
} as const
```

Pass a namespace to `useTranslation` to make it the default for that component. Reach another namespace with a `namespace:` prefix, and nested keys with dots:

```tsx
// app/features/orders/orders-header.tsx
import { useTranslation } from 'kitr/i18n'

export function OrdersHeader() {
  const { t } = useTranslation('orders')
  return (
    <header>
      <h1>{t('title')}</h1>
      <span>{t('status.open')}</span>
      <button type="button">{t('common:cancel')}</button>
    </header>
  )
}
```

That renders "Orders", "Open" and "Cancel". For a component that only reads one branch, `useTranslation('orders', { keyPrefix: 'status' })` lets you write `t('paid')` for `orders.status.paid`.

## Insert values

Wrap a placeholder in double braces in the string, and pass the value under the same name:

```tsx
// app/features/orders/assigned-to.tsx
import { useTranslation } from 'kitr/i18n'

export function AssignedTo({ order }: { order: { id: string; owner: string } }) {
  const { t } = useTranslation('orders')
  // orders.assigned: 'Order {{id}} is assigned to {{owner}}'
  return <p>{t('assigned', { id: order.id, owner: order.owner })}</p>
  // => Order 1001 is assigned to Grace
}
```

Values are inserted as they are, without HTML escaping: `t('hello', { name: '<b>Ada</b>' })` returns `Hello, <b>Ada</b>`. Rendered as React text that is safe, because React escapes it. Never pass a translated string to `dangerouslySetInnerHTML`; use [Trans](#put-markup-inside-a-string) for markup.

## Count things

Give a key one variant per plural form, and pass `count`. i18next picks the form with `Intl.PluralRules` for the current language:

```ts
// app/locales/en.ts
export default {
  orders: {
    count_zero: 'No orders',
    count_one: '{{count}} order',
    count_other: '{{count}} orders',
  },
} as const
```

```tsx
// app/features/orders/order-count.tsx
import { useTranslation } from 'kitr/i18n'

export function OrderCount({ count }: { count: number }) {
  const { t } = useTranslation('orders')
  return <p>{t('count', { count })}</p>
}
// count 0 => No orders
// count 1 => 1 order
// count 3 => 3 orders
```

Ask for `count`, never `count_one`. `_zero` is optional: without it, English uses `_other` and shows "0 orders". Other languages have other forms: Polish has `_few` and `_many`, Arabic six forms. Each language's bundle lists the forms that language needs; the [i18next plural guide](https://www.i18next.com/translation-function/plurals) lists them.

## Format numbers, money and dates

Name a formatter after the value inside the braces. The formatters use `Intl` with the current language, so the same key prints `€1,234.50` in English and `1.234,50 €` in German:

```ts
// app/locales/en.ts
export default {
  orders: {
    total: 'Total: {{amount, currency(EUR)}}',
    placed: 'Placed on {{date, datetime}}',
    items: '{{count, number}} items',
  },
} as const
```

```tsx
// app/features/orders/order-summary.tsx
import { useTranslation } from 'kitr/i18n'

export function OrderSummary({ order }: { order: { total: number; placedAt: Date } }) {
  const { t } = useTranslation('orders')
  return (
    <dl>
      <dd>{t('total', { amount: order.total })}</dd>
      <dd>{t('placed', { date: order.placedAt })}</dd>
    </dl>
  )
}
// en, total 1234.5 => Total: €1,234.50
// de, total 1234.5 => Summe: 1.234,50 €
// de, placedAt 2026-03-01 => Bestellt am 1.3.2026
```

The built-in formatters are `number`, `currency`, `datetime`, `relativetime` and `list`, each taking `Intl` options in parentheses. See [i18next formatting](https://www.i18next.com/translation-function/formatting). Keep amounts as numbers and dates as `Date` objects until they reach `t`; don't format them yourself first.

## Put markup inside a string

A sentence with a link or bold words in the middle can't be split into pieces without breaking the word order in other languages. Keep it as one string with numbered or named tags, and render it with `Trans`:

```ts
// app/locales/en.ts
export default {
  common: {
    welcome: 'Welcome back, <bold>{{name}}</bold>. <link>See your orders</link>.',
  },
} as const
```

```tsx
// app/features/orders/welcome-back.tsx
import { Trans } from 'kitr/i18n'

export function WelcomeBack({ name }: { name: string }) {
  return (
    <p>
      <Trans
        i18nKey="common:welcome"
        values={{ name }}
        components={{ bold: <strong />, link: <a href="https://app.acme.com/orders" /> }}
      />
    </p>
  )
}
```

`<WelcomeBack name="Ada" />` renders "Welcome back, **Ada**. See your orders." with "See your orders" as a link. The German bundle can move the tags anywhere in its sentence. [Trans in react-i18next's docs](https://react.i18next.com/latest/trans-component) covers the other forms.

## Add a language

Copy the English bundle, translate it, and list it in the config. Type the copy against the English one, so a missing or misspelled key fails the type check:

```ts
// app/locales/en.ts
const en = {
  common: { hello: 'Hello, {{name}}', save: 'Save' },
  orders: { title: 'Orders', empty: 'No orders yet' },
} as const

export default en

/** The shape every other locale must match: same keys, any strings. */
export type Bundle<T> = { [K in keyof T]: T[K] extends string ? string : Bundle<T[K]> }
```

```ts
// app/locales/de.ts
import type { Bundle } from './en'
import type en from './en'

const de = {
  common: { hello: 'Hallo, {{name}}', save: 'Speichern' },
  orders: { title: 'Bestellungen', empty: 'Noch keine Bestellungen' },
} as const satisfies Bundle<typeof en>

export default de
```

```ts
// config/i18n.ts
import { defineConfig } from 'kitr/i18n'
import de from '#app/locales/de'
import en from '#app/locales/en'

export default defineConfig({
  resources: { en, de },
  defaultLocale: 'en',
  defaultNS: 'common',
})
```

A key missing from `de.ts` is a type error. If one slips through anyway, a German page shows the English string, because `fallbackLng` is `defaultLocale`. Plural keys are the exception to "same keys": a language may need `_few` or `_many` forms that English doesn't have, so loosen `Bundle` for those namespaces.

## Type your keys

Tell i18next the shape of the English bundle once. Then `t()` autocompletes every key, checks the namespace prefix, and rejects typos at compile time:

```ts
// app/i18n.d.ts
import type en from '#app/locales/en'

declare module 'i18next' {
  interface CustomTypeOptions {
    defaultNS: 'common'
    resources: typeof en
  }
}
```

```tsx
// app/features/orders/orders-header.tsx
import { useTranslation } from 'kitr/i18n'

export function OrdersHeader() {
  const { t } = useTranslation('orders')
  return <h1>{t('titel')}</h1>
  // Type error: 'titel' is not a key of the orders namespace
}
```

When a component takes a key as a prop, type the prop with `TranslationKeys`. It flattens a namespace into its dotted key paths:

```tsx
// app/features/orders/status-badge.tsx
import { type TranslationKeys, useTranslation } from 'kitr/i18n'
import type en from '#app/locales/en'

type OrderKey = TranslationKeys<(typeof en)['orders']>
// => 'title' | 'empty' | 'status.open' | 'status.paid' | 'status.refunded'

export function StatusBadge({ label }: { label: OrderKey }) {
  const { t } = useTranslation('orders')
  return <span className="badge">{t(label)}</span>
}
```

`TranslationKeys<typeof en>` over the whole bundle gives `'common.hello' | 'orders.title' | ...`, with the namespace as the first dotted segment, not the `orders:` prefix `t()` expects. Pass one namespace, as above, for keys you hand to `t`.

## Switch the language

`i18n.changeLanguage()` switches every mounted component at once. Save the choice under `storageKey` so detection picks it on the next visit:

```tsx
// app/components/language-switch.tsx
import { useTranslation } from 'kitr/i18n'

const languages = { en: 'English', de: 'Deutsch' } as const

export function LanguageSwitch() {
  const { i18n } = useTranslation()
  return (
    <select
      value={i18n.resolvedLanguage}
      onChange={(event) => {
        const next = event.target.value
        localStorage.setItem('locale', next)
        void i18n.changeLanguage(next)
      }}
    >
      {Object.entries(languages).map(([code, label]) => (
        <option key={code} value={code}>
          {label}
        </option>
      ))}
    </select>
  )
}
```

`changeLanguage` does not write to `localStorage` itself; the `setItem` call does. It also does not touch `<html lang>`. Keep it in sync for screen readers and hyphenation by listening once, where the app starts:

```ts
// app/client.tsx
import { app } from './app'

app.boot().then(() => {
  const i18n = app.container.use('i18n')
  document.documentElement.lang = i18n.language
  i18n.on('languageChanged', (language) => {
    document.documentElement.lang = language
  })
  // ... then hydrate or render as before
})
```

A language that is not in `locales` (by default, not in `resources`) is never chosen: `changeLanguage('fr')` without a French bundle leaves `resolvedLanguage` on `en`.

## Detect the visitor's language

With `detect: true`, the provider picks the first language in this order:

1. `app.env.locale`, when the app was created with one.
2. The saved choice in `localStorage` under `storageKey`, when it is a supported language.
3. The browser's `navigator.languages`, matched against your languages.
4. `defaultLocale`.

Matching tries each browser language in order. An exact match wins; otherwise the base language matches (`en-GB` matches `en`), and a base language matches a regional bundle (`pt` matches `pt-BR`). `detectLocale(supported, storageKey)` runs steps 2 and 3 on their own:

```ts
// app/features/settings/language.ts
import { detectLocale } from 'kitr/i18n'

detectLocale(['en', 'de'])
// navigator.languages ['de-AT', 'en'] and nothing saved => 'de'
// localStorage locale = 'en' => 'en'
// on the server => undefined
```

Detection runs once, when the provider creates the instance at startup. With `detect: false`, the app starts in `app.env.locale` or `defaultLocale`, which is what you want when the server decides the language.

## Choose the language on the server

On the server there is no `navigator` and no `localStorage`; the `Accept-Language` header carries the visitor's preference. `matchLocale()` parses it, quality values and all, and returns the best supported language:

```ts
// server/controllers/locale_controller.ts
import type { HttpContext } from 'kitr/api'
import { matchLocale } from 'kitr/i18n'

export default class LocaleController {
  async show({ request }: HttpContext) {
    const header = request.header('accept-language') ?? ''
    return { locale: matchLocale(header, ['en', 'de']) ?? 'en' }
  }
}
```

What it returns for a few headers, with `['en', 'de']` supported:

| `Accept-Language` | Result |
| --- | --- |
| `de-CH,de;q=0.9,en;q=0.8` | `'de'` |
| `en-GB` | `'en'` |
| `fr-FR,fr;q=0.9` | `undefined` |
| `''` | `undefined` |

It reads the languages in the order the header lists them and does not sort by `q`; browsers already send them in preference order. It also takes an array, such as `navigator.languages`. A server-rendered app usually stores the choice in a cookie instead, so the server and the browser agree; the `site` kit does this with [storage](/packages/storage)'s `defineCookie`.

## Translate outside components

The provider binds the i18next instance as `i18n` in the container. Read it where there are no hooks, such as a toast after a mutation or a router loader:

```ts
// app/features/orders/notify.ts
import type { KitrApp } from 'kitr/app'

export function orderSavedMessage(app: KitrApp, orderId: string) {
  const i18n = app.container.use('i18n')
  return i18n.t('orders:saved', { id: orderId })
  // en => Order 1001 saved
}
```

On the server, for an email in the customer's language, create an instance from the same config and take a fixed `t` per language. `getFixedT` does not change the instance's language, so concurrent requests can't affect each other:

```ts
// server/mail/order_confirmation.ts
import { createI18n } from 'kitr/i18n'
import i18nConfig from '#config/i18n'

const i18n = createI18n({ ...i18nConfig, detect: false })

export function confirmationSubject(locale: string, count: number) {
  const t = i18n.getFixedT(locale, 'orders')
  return t('count', { count })
}
// confirmationSubject('de', 2) => 2 Bestellungen
```

Don't call `changeLanguage()` on an instance shared by every request. On a server, the language would switch under requests that are still rendering. Use `getFixedT`, or `i18n.cloneInstance({ lng })` for a per-request instance to hand to `I18nextProvider`, as the `site` kit's `LocaleProvider` does.

## Load a language on demand

Every bundle in `resources` ships in the main JavaScript bundle. With many languages, load the rarely used ones when they are chosen, and list them in `locales` up front so they can be chosen:

```ts
// app/features/settings/load-language.ts
import type { KitrApp } from 'kitr/app'

export async function useFrench(app: KitrApp) {
  const i18n = app.container.use('i18n')
  const { default: fr } = await import('#app/locales/fr')
  for (const [namespace, strings] of Object.entries(fr)) {
    i18n.addResourceBundle('fr', namespace, strings)
  }
  await i18n.changeLanguage('fr')
}
```

```ts
// config/i18n.ts
import { defineConfig } from 'kitr/i18n'
import de from '#app/locales/de'
import en from '#app/locales/en'

export default defineConfig({
  resources: { en, de },
  locales: ['en', 'de', 'fr'],
  defaultLocale: 'en',
  defaultNS: 'common',
})
```

Without `fr` in `locales`, the bundle loads but `changeLanguage('fr')` stays on English. For loading every language over HTTP, i18next has [backend plugins](https://www.i18next.com/overview/plugins-and-utils#backends).

## Handle missing keys

A key that exists in English but not in German shows the English string. A key that exists nowhere shows the key itself, without its namespace:

```ts
// app/features/orders/missing.ts
import type { KitrApp } from 'kitr/app'

export function demo(app: KitrApp) {
  const i18n = app.container.use('i18n')
  i18n.t('orders:refundNote')
  // => 'refundNote' when no bundle has it
}
```

Typed keys catch this at compile time. To also catch it at run time, for example to report keys a translator forgot, pass i18next's `saveMissing` and `missingKeyHandler` options in `config/i18n.ts`.

## Testing

Render translated components with [testing](/packages/testing)'s `createTestApp` and `renderWithKitr`. Pass the i18n provider and your config with `detect: false`, so the browser language of the test runner doesn't decide the result. Pass `env: { locale }` to render another language:

```tsx
// app/features/orders/orders-header.test.tsx
import { screen } from '@testing-library/react'
import { useTranslation } from 'kitr/i18n'
import i18nProvider from 'kitr/i18n/provider'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { describe, expect, it } from 'vitest'
import i18nConfig from '#config/i18n'

function OrdersHeader({ count, total }: { count: number; total: number }) {
  const { t } = useTranslation('orders')
  return (
    <header>
      <h1>{t('title')}</h1>
      <p>{t('count', { count })}</p>
      <p>{t('total', { amount: total })}</p>
    </header>
  )
}

const boot = (locale?: string) =>
  createTestApp({
    providers: [i18nProvider],
    config: { i18n: { ...i18nConfig, detect: false } },
    env: locale ? { locale } : {},
  })

describe('OrdersHeader', () => {
  it('renders in English by default', async () => {
    renderWithKitr(<OrdersHeader count={3} total={1234.5} />, { app: await boot() })

    expect(screen.getByRole('heading', { name: 'Orders' })).toBeTruthy()
    expect(screen.getByText('3 orders')).toBeTruthy()
    expect(screen.getByText('Total: €1,234.50')).toBeTruthy()
  })

  it('renders in German', async () => {
    renderWithKitr(<OrdersHeader count={1} total={1234.5} />, { app: await boot('de') })

    expect(screen.getByRole('heading', { name: 'Bestellungen' })).toBeTruthy()
    expect(screen.getByText('1 Bestellung')).toBeTruthy()
    expect(screen.getByText('Summe: 1.234,50 €')).toBeTruthy()
  })
})
```

The test assumes `orders.title`, `orders.count_one`, `orders.count_other` and `orders.total` in both bundles, as in the sections above. To test plain functions that call `t`, skip React and use `createI18n(i18nConfig, 'de').t(...)`. Tests that check a whole page in every language catch untranslated strings early: render it with `boot('de')` and assert that no English heading is on the screen.

## Next steps

- [API reference](/packages/i18n/api): every export of `kitr/i18n` and `kitr/i18n/provider`.
- [react-i18next docs](https://react.i18next.com): `useTranslation`, `Trans` and the rest, imported from `kitr/i18n`.
- [i18next docs](https://www.i18next.com): plurals, formatting, context and options.
- [Storage](/packages/storage): keep the visitor's language in a cookie the server can read.
- [Testing](/packages/testing): `createTestApp` and `renderWithKitr`.


# Jobs API

Source: https://kitr.dev/packages/jobs/api

Every export of `kitr/jobs`, `kitr/jobs/provider`, `kitr/jobs/kitr`, read from the published type definitions. The [guide](/packages/jobs) shows them in use.

## kitr/jobs

### createJobs

```ts
function createJobs(app: KitrApp, config?: JobsConfig): Jobs;
```

Create the jobs service without the provider, for scripts and tests. Takes the same options as `config/jobs.ts`.

### createMemoryJobsDriver

```ts
function createMemoryJobsDriver(): JobsDriver;
```

The default driver: an in-process queue sorted by `runAt`. Lost on restart and not shared between processes.

### cronMatches

```ts
function cronMatches(expression: string, date: Date): boolean;
```

Does a 5-field cron expression (minute hour day month weekday) match this minute?

### defineJob

```ts
function defineJob<Payload = void>(name: string, options: JobOptions<Payload>): Job<Payload>;
```

Declare a background job. List it in `config/jobs.ts`, then queue it with `useJobs(app).dispatch(job, payload)`.

### parseInterval

```ts
function parseInterval(text: string): number;
```

Parse an interval such as `'30s'`, `'5m'` or `'1.5h'` into milliseconds (`'5m'` → 300000). Throws on anything else.

### useJobs

```ts
function useJobs(app: KitrApp): Jobs;
```

The jobs service the provider bound in this app's container. Throws in the browser, where nothing is bound.

### defineConfig

```ts
const defineConfig: <const C extends JobsConfig>(config: C) => C;
```

Types `config/jobs.ts`. Returns its argument unchanged.

### DispatchOptions

```ts
interface DispatchOptions {
  /** Milliseconds from now. */
  delay?: number;
  /** A fixed time instead. */
  at?: Date;
}
```

The third argument of `dispatch()`: when the job may run.

### Job

```ts
interface Job<Payload = unknown> extends JobOptions<Payload> {
  /** Identifies the job in the queue; keep it stable across deploys. */
  name: string;
  /** The payload type, for inference only. */
  readonly __payload?: Payload;
}
```

A job made by `defineJob`: its options plus the name the queue refers to it by.

### JobContext

```ts
interface JobContext {
  /** The app, for the container and services such as `useMailer(app)`. */
  app: KitrApp;
  /** 1 on the first run, then one more per retry. */
  attempt: number;
  /** The id `dispatch()` returned; the same across retries. */
  jobId: string;
  /** Aborts when the attempt passes its `timeout`; pass it to fetch and database calls. */
  signal: AbortSignal;
}
```

The second argument of a job's `run`: the app, the attempt number, the job id and an abort signal.

### JobOptions

```ts
interface JobOptions<Payload> {
  /** Validates the payload when dispatched and when a queue driver hands it back. */
  schema?: StandardSchemaV1<unknown, Payload>;
  /** Retries after a failure. Default 3. */
  retries?: number;
  /** Milliseconds before the first retry, doubled each time. Default 1000. */
  backoff?: number;
  /** Milliseconds a run may take before it is aborted. Default 60 000. */
  timeout?: number;
  /** Run on a schedule: a 5-field cron expression or an `every` interval such as `'5m'`, `'1h'`. */
  schedule?: string | {
    every: string;
  };
  /** The work. Throw to fail the attempt; the return value is what `jobs.run()` resolves with. */
  run(payload: Payload, ctx: JobContext): Promise<unknown> | unknown;
}
```

What `defineJob` takes: the work, plus its schema, retries, backoff, timeout and schedule.

### Jobs

```ts
interface Jobs {
  /** Add jobs after creation, checking their schedules. Returns the service for chaining. */
  register(...jobs: Job<any>[]): Jobs;
  /** Validate the payload and queue the job; resolves with its id. */
  dispatch<P>(job: Job<P>, payload: P, options?: DispatchOptions): Promise<string>;
  /** Run a job now, in this process, with retries; what the worker does. */
  run<P>(job: Job<P>, payload: P, attempt?: number): Promise<unknown>;
  /** Start polling the queue and dispatching scheduled jobs. Idempotent. */
  start(): void;
  /** Stop polling and wait for running jobs to settle. */
  stop(): Promise<void>;
  /** Whether the worker is polling. */
  readonly running: boolean;
  /** The queue driver. */
  readonly driver: JobsDriver;
  /** Known jobs by name. */
  readonly jobs: ReadonlyMap<string, Job<any>>;
}
```

The service the provider binds as `jobs`: queue, run and schedule jobs, and control the worker.

### JobsConfig

```ts
interface JobsConfig {
  /** Jobs the worker knows about (`server/jobs/*.ts`). Dispatching by object registers on the fly. */
  jobs?: Job<any>[];
  /** Where queued jobs wait. Default: the in-memory driver, lost on restart. */
  driver?: JobsDriver;
  /** Jobs run at once per process. Default 5. */
  concurrency?: number;
  /** Milliseconds between queue polls. Default 500. */
  pollInterval?: number;
  /** Start the worker when the server starts. Default true; set false for a separate worker process. */
  worker?: boolean;
  /** Called when a job has used up its retries. */
  onFailed?: (job: QueuedJob, error: unknown) => void;
}
```

The options in `config/jobs.ts`.

### JobsDriver

```ts
interface JobsDriver {
  /** Identifies the driver, such as `memory` or `redis`. */
  name: string;
  /** Store a job; called by `dispatch()` and for each retry. */
  push(job: QueuedJob): Promise<void>;
  /** Jobs whose `runAt` has passed, removed from the queue. */
  pull(now: number, limit: number): Promise<QueuedJob[]>;
  /** How many jobs are waiting. */
  size(): Promise<number>;
  /** Remove every waiting job. */
  clear(): Promise<void>;
}
```

Where queued work waits. The memory driver is the default; Redis or a table are a few methods.

### QueuedJob

```ts
interface QueuedJob {
  /** The id `dispatch()` returned. */
  id: string;
  /** The job's name. */
  name: string;
  /** The payload as validated at dispatch; must survive JSON for shared drivers. */
  payload: unknown;
  /** 1 for the first run, one more per retry. */
  attempt: number;
  /** ms epoch when it may run. */
  runAt: number;
}
```

A job waiting in the queue, as drivers store it and `onFailed` receives it.

## kitr/jobs/provider

### jobsProvider

```ts
const jobsProvider: import("@kitr/core").KitrProvider;
```

Binds `jobs` from `config/jobs.ts`. The worker starts when the server is ready and drains
on shutdown; `worker: false` leaves starting to a separate process (`jobs.start()`).

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Jobs

Source: https://kitr.dev/packages/jobs

Some work should not keep a request waiting: emailing an invoice, generating a PDF, syncing orders with a payment provider, pruning expired sessions at 3am. `kitr/jobs` hands that work to a background worker. You define a job with a typed payload, dispatch it from a controller, and the worker runs it with retries, exponential backoff, a timeout and an optional cron or interval schedule.

The examples on this page follow one scenario: Acme's app at `app.acme.com` generates a monthly invoice for each team, emails it to the team owner, and cleans up old data every night.

`kitr/jobs` runs on the server only, with no dependencies beyond kitr. The built-in queue lives in the server's memory, which suits one process. For several servers, or for jobs that must survive a restart, give it a shared driver ([Extend](#extend)). For work that must finish before the response (charging a card), call the code directly instead of dispatching a job.

## Install

```sh
kitr add jobs
```

What `kitr add` does:

- Installs `@kitr/jobs`. Jobs require the [server](/packages/server) package, so `kitr add` also adds `server` (and its `logger`) when the project does not have them yet.
- Adds `'@kitr/jobs'` to `packages` and `() => import('@kitr/jobs/provider')` to `providers` in `kitrrc.ts`.
- Writes `config/jobs.ts` (shown in [Configure](#configure)) and regenerates `config/index.ts`.
- Writes an example job, `server/jobs/example.ts`, exporting `exampleJob`.
- Adds a `## kitr: jobs` section to `AGENTS.md` telling coding agents to put background work in `server/jobs/` and never `setTimeout` work in a request.

`kitr add jobs` adds no env variables or scripts and asks no questions. To edit `package.json` without running the package manager, pass the global flag:

```sh
kitr add jobs --no-install
```

No kit includes jobs; add it to any kit with a server platform.

`kitr remove jobs` reverses the provider, `packages` entry, dependency and `AGENTS.md` steps, and deletes `config/jobs.ts`. Your jobs in `server/jobs/` stay.

## Configure

`kitr add jobs` writes this file:

```ts
// config/jobs.ts
import { defineConfig } from 'kitr/jobs'
import { exampleJob } from '#server/jobs/example'

export default defineConfig({
  // Every job the worker runs (kitr make:job <name> writes one in server/jobs/).
  jobs: [exampleJob],
  // In-memory queue by default: fine for one process. For several, pass a shared driver.
  concurrency: 5,
  worker: true, // false when a separate worker process runs the jobs
})
```

| Option | Default | Description |
| --- | --- | --- |
| `jobs` | `[]` | Every job the worker can run. A queued job whose name is not here, and was not dispatched by this process, is dropped with a warning. Schedules only run for jobs listed here or passed to `register()`. |
| `driver` | the memory driver | Where queued jobs wait. See [Extend](#extend). |
| `concurrency` | `5` | How many jobs run at once in each process. |
| `pollInterval` | `500` | Milliseconds between checks of the queue. |
| `worker` | `true` | Start the worker when the server starts. `false` when a separate process runs jobs. |
| `onFailed(job, error)` | none | Called when a job has used up its retries, or its payload fails the schema. Receives the `QueuedJob` and the last error. |

Per-job options (`retries`, `backoff`, `timeout`, `schedule`) live on the job itself; see [Define a job](#define-a-job).

`kitr/jobs` reads no env variables. Use your own in `config/jobs.ts` when a setting changes per deploy, as in [Run the worker in its own process](#run-the-worker-in-its-own-process).

## Dispatch your first job

Generate a job:

```sh
kitr make:job generate-invoice
```

That writes `server/jobs/generate_invoice.ts`. Edit it to build a team's invoice for a month:

```ts
// server/jobs/generate_invoice.ts
import { defineJob } from 'kitr/jobs'
import { z } from 'zod'

export const generateInvoiceInput = z.object({
  teamId: z.string(),
  month: z.string().regex(/^\d{4}-\d{2}$/),
})

export const generateInvoice = defineJob('generate_invoice', {
  schema: generateInvoiceInput,
  retries: 3,
  async run({ teamId, month }, { attempt }) {
    // Load the team's usage, render the PDF, store it under storage/invoices/.
    return { invoiceNumber: `INV-${month}-${teamId}`, attempt }
  },
})
```

List it in `config/jobs.ts`, next to the example:

```ts
// config/jobs.ts
import { defineConfig } from 'kitr/jobs'
import { exampleJob } from '#server/jobs/example'
import { generateInvoice } from '#server/jobs/generate_invoice'

export default defineConfig({
  jobs: [exampleJob, generateInvoice],
  concurrency: 5,
  worker: true,
})
```

Dispatch it from a controller. `dispatch()` checks the payload, queues the job and resolves with its id straight away:

```ts
// server/controllers/invoices_controller.ts
import type { HttpContext } from 'kitr/api'
import { useJobs } from 'kitr/jobs'
import { generateInvoice } from '#server/jobs/generate_invoice'

export default class InvoicesController {
  async store({ app, params, response }: HttpContext<{ teamId: string }>) {
    const jobId = await useJobs(app).dispatch(generateInvoice, {
      teamId: params.teamId,
      month: '2026-10',
    })
    return response.json({ jobId }, { status: 202 })
    // => { "jobId": "3f0c9a52-6b1e-4d7a-9a51-0e2f8c1d7b44" }
  }
}
```

Register the route with `api.post('/teams/:teamId/invoices', [InvoicesController, 'store'])` in `server/routes.ts`. The request answers at once with the job id. Within half a second (`pollInterval`) the worker in the same process picks the job up and runs it.

The payload is typed from the schema, so a missing `month` is a type error. A wrong value at run time, such as `month: 'October'`, makes `dispatch()` throw a `KitrError` with code `VALIDATION` before anything is queued; in a controller that becomes a 422 response.

## Define a job

`defineJob(name, options)` returns a job object. The name is how the queue refers to it, so keep it stable across deploys: a queued job whose name no longer exists is dropped.

| Option | Default | Description |
| --- | --- | --- |
| `run(payload, ctx)` | required | The work. Its return value is what `jobs.run()` resolves with. |
| `schema` | none | A [Standard Schema](https://standardschema.dev) (zod, valibot, arktype). Checked at dispatch and again when the worker picks the job up. |
| `retries` | `3` | Retries after a failure. `3` means up to 4 attempts in all. |
| `backoff` | `1000` | Milliseconds before the first retry. It doubles each time: 1s, 2s, 4s. |
| `timeout` | `60000` | Milliseconds a run may take. Then its `signal` aborts and the attempt fails. |
| `schedule` | none | A 5-field cron expression or `{ every: '5m' }`. See [Run a job on a schedule](#run-a-job-on-a-schedule). |

The second argument of `run` is the `JobContext`:

| Field | Description |
| --- | --- |
| `app` | The app, for `app.container.use(...)` and `useMailer(app)`. |
| `attempt` | `1` on the first run, one more per retry. |
| `jobId` | The id `dispatch()` returned. Stays the same across retries. |
| `signal` | An `AbortSignal` that aborts at the timeout. Pass it to `fetch` and database calls. |

Without a schema, the type parameter types the payload: `defineJob<{ teamId: string }>('notify_team', { run: ... })`. With one, the payload type comes from the schema. A job with no payload is dispatched with `undefined`: `dispatch(pruneSessions, undefined)`.

## Dispatch a job

On the server, `useJobs(app).dispatch(job, payload, options?)` queues a job and resolves with its id. It works in controllers, actions, services and other jobs:

```ts
// server/jobs/close_month.ts
import { defineJob, useJobs } from 'kitr/jobs'
import { generateInvoice } from '#server/jobs/generate_invoice'

/** Fans out one invoice job per team. */
export const closeMonth = defineJob<{ month: string; teamIds: string[] }>('close_month', {
  async run({ month, teamIds }, { app }) {
    const jobs = useJobs(app)
    const ids = await Promise.all(teamIds.map((teamId) => jobs.dispatch(generateInvoice, { teamId, month })))
    return ids.length
  },
})
```

| Where | How to reach the queue |
| --- | --- |
| A controller | `useJobs(ctx.app)` |
| A job | `useJobs(ctx.app)` in `run(payload, ctx)` |
| An action or service during a request | `useJobs(useRequestApp())`, with `useRequestApp` from `kitr/server` |
| A script | `useJobs(server.app)` after `await server.boot()` |

`useJobs(app)` is `app.container.use('jobs')`. The provider binds nothing in the browser.

Pass ids and small plain values in the payload, not whole records. With a shared driver the payload is stored as data, and the job should load fresh records when it runs.

Don't `setTimeout(() => sendEmail(), 0)` in a request handler. The work has no retries, nothing waits for it at shutdown, and an error in it is lost. Dispatch a job.

## Delay a job

Pass `delay` in milliseconds, or `at` for a fixed time:

```ts
// server/services/trial_service.ts
import type { KitrApp } from 'kitr/app'
import { useJobs } from 'kitr/jobs'
import { generateInvoice } from '#server/jobs/generate_invoice'

export async function scheduleFirstInvoice(app: KitrApp, teamId: string) {
  const jobs = useJobs(app)
  // Ten minutes from now.
  await jobs.dispatch(generateInvoice, { teamId, month: '2026-11' }, { delay: 10 * 60_000 })
  // On the first of next month, 09:00 UTC.
  await jobs.dispatch(
    generateInvoice,
    { teamId, month: '2026-11' },
    { at: new Date('2026-12-01T09:00:00Z') },
  )
}
```

| Option | Description |
| --- | --- |
| `delay` | Milliseconds from now. |
| `at` | A `Date`. Takes precedence over `delay`. A time in the past runs at the next poll. |

The job is queued at once with that `runAt` time, and the worker leaves it until then. With the memory driver a delayed job is lost if the process restarts before it runs.

## Run a job on a schedule

Give a job a `schedule` and list it in `config/jobs.ts`. The worker dispatches it itself; you never call `dispatch()`:

```ts
// server/jobs/prune_sessions.ts
import { defineJob } from 'kitr/jobs'

/** Every day at 03:00 server time. */
export const pruneSessions = defineJob('prune_sessions', {
  schedule: '0 3 * * *',
  async run(_payload, { app }) {
    app.container.use('logger').info('pruning expired sessions')
  },
})
```

```ts
// server/jobs/sync_orders.ts
import { defineJob } from 'kitr/jobs'

/** Every five minutes, starting when the worker starts. */
export const syncOrders = defineJob('sync_orders', {
  schedule: { every: '5m' },
  timeout: 4 * 60_000,
  async run(_payload, { signal }) {
    const res = await fetch('https://payments.acme.com/orders?since=5m', { signal })
    return res.status
  },
})
```

Cron expressions have five fields, read in the server's local time zone:

| Field | Range | Example |
| --- | --- | --- |
| minute | `0`–`59` | `*/15`: every 15 minutes |
| hour | `0`–`23` | `9-17`: office hours |
| day of month | `1`–`31` | `1`: the first |
| month | `1`–`12` | `1,4,7,10`: each quarter |
| weekday | `0`–`7`, `0` and `7` are Sunday | `1-5`: weekdays |

Each field takes `*`, a number, a list (`1,15`), a range (`1-5`) and a step (`*/10`, `5/15`, `0-30/10`). Names like `MON` or `JAN` are not supported. When both day of month and weekday are set, either may match, as in standard cron: `0 0 1 * 1` runs on the 1st and on every Monday.

Intervals take a number and a unit: `250ms`, `30s`, `5m`, `1.5h`, `1d`. An interval job runs once as soon as the worker starts, then every interval after its last dispatch.

A scheduled job is dispatched with an `undefined` payload, so it cannot have a schema that rejects `undefined`. If it does, the worker logs `[jobs] could not queue scheduled <name>` every time and the job never runs.

A bad expression in `register()` throws at once: `[kitr/jobs] Bad cron "61 * * * *" (field "61")`. A bad interval in `config/jobs.ts` throws when the app boots. A bad cron expression in `config/jobs.ts` is not checked at boot; the worker logs `[jobs] worker poll failed` once a minute instead. Check new expressions with `cronMatches()`:

```ts
// scripts/check_cron.ts
import { cronMatches, parseInterval } from 'kitr/jobs'

cronMatches('0 3 * * *', new Date(2026, 10, 7, 3, 0)) // => true
cronMatches('*/15 9-17 * * 1-5', new Date(2026, 10, 7, 9, 30)) // => false, a Saturday
parseInterval('5m') // => 300000
```

Every process with a running worker dispatches scheduled jobs. With two web servers that both run the worker, `prune_sessions` runs twice. Run the worker in one process, as below.

## Retry a failing job

When `run` throws or times out, the worker queues the job again after `backoff × 2^(attempt - 1)` milliseconds, until it has used its retries:

```ts
// server/jobs/send_invoice_email.ts
import { defineJob } from 'kitr/jobs'
import { useMailer } from 'kitr/mail'
import { z } from 'zod'
import { invoiceReadyMail } from '#server/mail/invoice_ready'

export const sendInvoiceEmail = defineJob('send_invoice_email', {
  schema: z.object({ teamName: z.string(), invoiceNumber: z.string(), email: z.string() }),
  retries: 5,
  backoff: 10_000,
  async run({ teamName, invoiceNumber, email }, { app }) {
    await useMailer(app).send(invoiceReadyMail, { teamName, invoiceNumber, total: '$480.00' }, { to: email })
  },
})
```

With `retries: 5` and `backoff: 10_000`, a mail outage is retried after 10s, 20s, 40s, 80s and 160s, then given up. The logger shows each step:

```
WARN  09:00:10.112 [app] [jobs] send_invoice_email failed (attempt 1), retry in 10000ms
WARN  09:00:20.140 [app] [jobs] send_invoice_email failed (attempt 2), retry in 20000ms
...
ERROR 09:05:10.301 [app] [jobs] send_invoice_email failed after 6 attempts
```

A payload that fails the schema when the worker picks it up is dropped without a retry, since it would fail every time, and logged as `[jobs] <name> dropped: bad payload`. Make `run` safe to repeat: a job that fails after charging a card is retried, and charges again unless you check first.

## Handle a job that keeps failing

`onFailed` in `config/jobs.ts` runs when a job has used its retries or its payload was rejected. It is the place to alert someone:

```ts
// config/jobs.ts
import { defineConfig } from 'kitr/jobs'
import { generateInvoice } from '#server/jobs/generate_invoice'
import { sendInvoiceEmail } from '#server/jobs/send_invoice_email'

export default defineConfig({
  jobs: [generateInvoice, sendInvoiceEmail],
  onFailed(job, error) {
    console.error(`job ${job.name} (${job.id}) gave up after ${job.attempt} attempts`, error)
  },
})
```

`job` is the `QueuedJob`:

| Field | Description |
| --- | --- |
| `id` | The id `dispatch()` returned. |
| `name` | The job's name. |
| `payload` | The payload as queued. |
| `attempt` | The attempt that failed last. |
| `runAt` | When that attempt was due, in milliseconds since the epoch. |

`onFailed` has no `app`. To report through [monitoring](/packages/monitoring), catch and report inside `run` with `ctx.app`, and rethrow so the job still retries:

```ts
// server/jobs/generate_invoice.ts
import { defineJob } from 'kitr/jobs'

export const generateInvoice = defineJob<{ teamId: string; month: string }>('generate_invoice', {
  retries: 3,
  async run({ teamId, month }, { app, attempt }) {
    try {
      return { invoiceNumber: `INV-${month}-${teamId}` }
    } catch (error) {
      app.container.use('monitoring').captureException(error, { extra: { teamId, month, attempt } })
      throw error
    }
  },
})
```

## Time out a stuck job

Each attempt gets `timeout` milliseconds, 60 seconds by default. At the limit, `ctx.signal` aborts and the attempt fails with `[jobs] <name> timed out after <ms>ms`, which counts as a failure and is retried. Pass the signal to anything that accepts one, so the work really stops:

```ts
// server/jobs/export_projects.ts
import { defineJob } from 'kitr/jobs'

export const exportProjects = defineJob<{ teamId: string }>('export_projects', {
  timeout: 5 * 60_000,
  retries: 1,
  async run({ teamId }, { signal }) {
    const res = await fetch(`https://exports.acme.com/teams/${teamId}`, { method: 'POST', signal })
    if (!res.ok) throw new Error(`export failed: ${res.status}`)
    return res.status
  },
})
```

A job that ignores its signal still fails at the timeout and frees its worker slot, but its code keeps running in the background until it finishes on its own.

## Run a job inline

`useJobs(app).run(job, payload)` runs a job now, in this process, with its retries and timeout, and resolves with what `run` returned. Nothing is queued:

```ts
// scripts/backfill_invoices.ts
import { useJobs } from 'kitr/jobs'
import { generateInvoice } from '#server/jobs/generate_invoice'
import { server } from '#server/main'

await server.boot()
const result = await useJobs(server.app).run(generateInvoice, { teamId: 'team_engines', month: '2026-09' })
// => { invoiceNumber: 'INV-2026-09-team_engines', attempt: 1 }
await server.close()
```

When every attempt fails, `run()` throws the last error. It waits the real backoff between attempts, and it does not call `onFailed`. A payload that fails the schema throws a `VALIDATION` error at once, without retrying.

## Run the worker in its own process

By default the worker runs inside the web server: it starts when `server.listen()` runs, or on the first request served through `server.fetch()` outside tests, and drains on shutdown. That suits one server.

With several web servers, or long jobs that should not compete with requests, run one worker process and turn the worker off in the web servers. The queue must then be shared between processes, so this needs a shared driver ([Extend](#extend)); with the memory driver, a job dispatched in the web server never reaches the worker.

```ts
// config/jobs.ts
import { defineConfig } from 'kitr/jobs'
import { generateInvoice } from '#server/jobs/generate_invoice'
import { pruneSessions } from '#server/jobs/prune_sessions'
import { createRedisJobsDriver } from '#server/jobs/redis_driver'

export default defineConfig({
  jobs: [generateInvoice, pruneSessions],
  driver: createRedisJobsDriver(process.env.REDIS_URL ?? 'redis://localhost:6379'),
  // JOBS_WORKER=off on the web servers: they only queue, the worker process runs jobs.
  worker: process.env.JOBS_WORKER !== 'off',
})
```

```ts
// server/worker.ts
import { useJobs } from 'kitr/jobs'
import { server } from '#server/main'

await server.boot()
const jobs = useJobs(server.app)
jobs.start()
server.logger.info('worker started', { jobs: [...jobs.jobs.keys()] })

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.once(signal, async () => {
    // Waits for running jobs, then runs every provider's shutdown.
    await server.close()
    process.exit(0)
  })
}
```

Deploy the web servers with `JOBS_WORKER=off`, and start one worker next to them with `tsx server/worker.ts`. It calls `start()` itself, so the setting does not matter there; in development, with the variable unset, the web server runs the worker as before. `server/main.ts` only listens when it is the entry file, so importing it here boots the app without opening a port.

`jobs.stop()` stops polling and waits for running jobs. Each job waits at most its timeout. Set your platform's shutdown grace period above your longest job timeout.

## Read the queue

The `Jobs` service exposes its state for health checks and admin pages:

```ts
// server/controllers/admin_jobs_controller.ts
import type { HttpContext } from 'kitr/api'
import { useJobs } from 'kitr/jobs'

export default class AdminJobsController {
  async show({ app }: HttpContext) {
    const jobs = useJobs(app)
    return {
      driver: jobs.driver.name,
      running: jobs.running,
      queued: await jobs.driver.size(),
      jobs: [...jobs.jobs.keys()],
    }
    // => { driver: 'memory', running: true, queued: 0, jobs: ['example', 'generate_invoice'] }
  }
}
```

| Member | Description |
| --- | --- |
| `register(...jobs)` | Add jobs after boot. Returns the service, so calls chain. Checks cron and interval syntax. |
| `dispatch(job, payload, options?)` | Queue a job; resolves with its id. |
| `run(job, payload, attempt?)` | Run a job inline with retries; resolves with its result. |
| `start()` | Start polling. Calling it twice does nothing. |
| `stop()` | Stop polling and wait for running jobs. |
| `running` | Whether the worker is polling. |
| `driver` | The queue driver. |
| `jobs` | A map of known jobs by name. |

`dispatch()` registers a job it does not know yet, in this process only. Always list jobs in `config/jobs.ts`, so a separate worker knows them too.

## Errors

| Error | When | What to do |
| --- | --- | --- |
| `KitrError` `VALIDATION` (422), message `[jobs] <name>: bad payload` | `dispatch()` or `run()` with a payload the schema rejects. `error.fieldErrors` lists the fields. | Fix the payload. In a controller it becomes a 422 response. |
| `[kitr/jobs] Bad cron "<expr>" (5 fields)` | A cron expression without exactly five fields. | Use `minute hour day month weekday`. |
| `[kitr/jobs] Bad cron "<expr>" (field "<field>")` | A field out of range, a name like `MON`, or a step of `0`. | See the table in [Run a job on a schedule](#run-a-job-on-a-schedule). |
| `[kitr/jobs] Bad interval "<text>" (use 30s, 5m, 1h, 1d)` | `{ every }` without a number and a unit. | Write `5m`, not `5 minutes`. |
| `[jobs] <name> timed out after <ms>ms` | An attempt ran past `timeout`. Counts as a failure. | Raise `timeout`, or pass `signal` to the slow call. |

The worker never throws: it logs these messages through the app's [logger](/packages/logger) instead.

| Log line | Level | Meaning |
| --- | --- | --- |
| `[jobs] <name> failed (attempt <n>), retry in <ms>ms` | warn | An attempt failed and the job is queued again. |
| `[jobs] <name> failed after <n> attempts` | error | Retries used up; `onFailed` runs. |
| `[jobs] <name> dropped: bad payload` | error | The queued payload failed the schema; `onFailed` runs. |
| `[jobs] unknown job "<name>" dropped` | warn | No job with that name is listed in this process. |
| `[jobs] could not queue scheduled <name>` | error | A scheduled dispatch failed, usually a schema that rejects `undefined`. |
| `[jobs] worker poll failed` | error | The driver threw (Redis restarted) or a cron expression is bad. The worker keeps polling. |

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:job <name>` | Writes a job to `server/jobs/<snake_name>.ts`. `--force` overwrites an existing file. |
| `kitr eject stub job` | Copies the generator's template to `stubs/job.ts`, so `make:job` writes your own starting point. |

`kitr make:job generate-invoice` writes `server/jobs/generate_invoice.ts`:

```ts
// server/jobs/generate_invoice.ts
import { defineJob } from 'kitr/jobs'
import { z } from 'zod'

export const generateInvoiceInput = z.object({
  id: z.string(),
})

/** List it in config/jobs.ts, then dispatch with `useJobs(app).dispatch(generateInvoice, { id })`; it runs on the worker with retries. */
export const generateInvoice = defineJob('generate_invoice', {
  schema: generateInvoiceInput,
  retries: 3,
  // schedule: { every: '1h' },
  async run({ id }, ctx) {
    console.info(`generate_invoice ${id} (attempt ${ctx.attempt})`)
  },
})
```

The generator does not add the job to `config/jobs.ts`; add it to `jobs` yourself.

## Testing

In a test the worker does not start: `createTestApp()` boots the app but does not run the providers' `ready` step. Dispatched jobs wait in the memory queue, where you can read them, and `jobs.run()` runs one inline:

```ts
// test/generate_invoice.test.ts
import { useJobs } from 'kitr/jobs'
import jobsProvider from 'kitr/jobs/provider'
import { createTestApp } from 'kitr/testing'
import { describe, expect, it } from 'vitest'
import { generateInvoice } from '#server/jobs/generate_invoice'

describe('generate_invoice', () => {
  it('queues the job with its payload', async () => {
    const app = await createTestApp({
      providers: [jobsProvider],
      config: { jobs: { jobs: [generateInvoice] } },
    })
    const jobs = useJobs(app)

    const id = await jobs.dispatch(generateInvoice, { teamId: 'team_engines', month: '2026-10' })

    expect(jobs.running).toBe(false)
    expect(await jobs.driver.size()).toBe(1)
    const [queued] = await jobs.driver.pull(Date.now(), 10)
    expect(queued).toMatchObject({
      id,
      name: 'generate_invoice',
      payload: { teamId: 'team_engines', month: '2026-10' },
      attempt: 1,
    })
  })

  it('builds the invoice number', async () => {
    const app = await createTestApp({ providers: [jobsProvider] })
    const result = await useJobs(app).run(generateInvoice, {
      teamId: 'team_engines',
      month: '2026-10',
    })
    expect(result).toEqual({ invoiceNumber: 'INV-2026-10-team_engines', attempt: 1 })
  })

  it('rejects a bad month before queueing', async () => {
    const app = await createTestApp({ providers: [jobsProvider] })
    const jobs = useJobs(app)
    await expect(
      jobs.dispatch(generateInvoice, { teamId: 'team_engines', month: 'October' }),
    ).rejects.toMatchObject({ code: 'VALIDATION', status: 422 })
    expect(await jobs.driver.size()).toBe(0)
  })
})
```

`driver.pull()` removes what it returns, which is what you want at the end of a test. To check a delay, pull at a later time: `jobs.driver.pull(Date.now() + 10 * 60_000, 10)`.

`jobs.run()` waits the real backoff between attempts, so a failing job with the defaults takes 7 seconds to give up. To test failure handling, pass `retries: 0` on a test job, or keep `backoff` small:

```ts
// test/flaky_job.test.ts
import { createJobs, defineJob } from 'kitr/jobs'
import { createTestApp } from 'kitr/testing'
import { expect, it } from 'vitest'

it('retries until the third attempt succeeds', async () => {
  const jobs = createJobs(await createTestApp())
  const attempts: number[] = []
  const flaky = defineJob('sync_orders_flaky', {
    retries: 2,
    backoff: 1,
    run: (_payload, { attempt }) => {
      attempts.push(attempt)
      if (attempt < 3) throw new Error('payments API down')
      return 'synced'
    },
  })
  expect(await jobs.run(flaky, undefined)).toBe('synced')
  expect(attempts).toEqual([1, 2, 3])
})
```

To test the worker loop itself, start it with a short poll and wait for the effect, then stop it:

```ts
// test/worker.test.ts
import { createJobs, defineJob } from 'kitr/jobs'
import { createTestApp } from 'kitr/testing'
import { expect, it, vi } from 'vitest'

it('runs dispatched jobs on the worker', async () => {
  const done: string[] = []
  const notify = defineJob<string>('notify_team', { run: (teamId) => void done.push(teamId) })
  const jobs = createJobs(await createTestApp(), { jobs: [notify], pollInterval: 5 })
  jobs.start()
  await jobs.dispatch(notify, 'team_engines')
  await vi.waitFor(() => expect(done).toEqual(['team_engines']))
  await jobs.stop()
})
```

`createJobs(app, config)` builds the service without the provider, with the same options as `config/jobs.ts`.

## Extend

A driver is where queued jobs wait. It has four methods; the worker calls `pull(now, limit)` every `pollInterval` and runs what comes back. See [`JobsDriver`](/packages/jobs/api#jobsdriver) and [`QueuedJob`](/packages/jobs/api#queuedjob).

| Method | Must |
| --- | --- |
| `push(job)` | Store a `QueuedJob`. Called by `dispatch()` and for every retry. |
| `pull(now, limit)` | Return up to `limit` jobs whose `runAt` is at or before `now`, earliest first, and remove them so no other worker gets them. |
| `size()` | Count the jobs waiting. |
| `clear()` | Remove every job. |

This driver keeps the queue in a [Redis](https://redis.io/docs/latest/develop/data-types/sorted-sets/) sorted set scored by `runAt`, with [ioredis](https://github.com/redis/ioredis) (`pnpm add ioredis`). Each job is claimed with `ZREM`, so two workers never run the same one:

```ts
// server/jobs/redis_driver.ts
import Redis from 'ioredis'
import type { JobsDriver, QueuedJob } from 'kitr/jobs'

export function createRedisJobsDriver(url: string, key = 'acme:jobs'): JobsDriver {
  const redis = new Redis(url)
  return {
    name: 'redis',
    async push(job) {
      await redis.zadd(key, job.runAt, JSON.stringify(job))
    },
    async pull(now, limit) {
      const due = await redis.zrangebyscore(key, 0, now, 'LIMIT', 0, limit)
      const claimed: QueuedJob[] = []
      for (const entry of due) {
        // Only the worker whose ZREM removes the entry runs it.
        if ((await redis.zrem(key, entry)) === 1) claimed.push(JSON.parse(entry) as QueuedJob)
      }
      return claimed
    },
    async size() {
      return redis.zcard(key)
    },
    async clear() {
      await redis.del(key)
    },
  }
}
```

Register it in `config/jobs.ts`:

```ts
// config/jobs.ts
import { defineConfig } from 'kitr/jobs'
import { generateInvoice } from '#server/jobs/generate_invoice'
import { createRedisJobsDriver } from '#server/jobs/redis_driver'

export default defineConfig({
  jobs: [generateInvoice],
  driver: createRedisJobsDriver(process.env.REDIS_URL ?? 'redis://localhost:6379'),
})
```

Payloads pass through `JSON.stringify`, so keep them to plain JSON: a `Date` comes back as a string, and the schema check on pull catches the mismatch. A job is removed from the queue when it is pulled, before it runs. If the process dies mid-run, the job is gone, so a driver that must never lose work moves pulled jobs to a processing list and pushes them back when they are not acknowledged in time. The same four methods fit a database table: `pull` selects due rows and deletes them in one transaction.

## Next steps

- [Jobs API reference](/packages/jobs/api): every export with its signature.
- [Mail](/packages/mail): send email from a job.
- [Logger](/packages/logger): where the worker's warnings and errors go.
- [Monitoring](/packages/monitoring): report jobs that keep failing.
- [Server](/packages/server): the lifecycle that starts and stops the worker.
- [Standard Schema](https://standardschema.dev): the schema libraries a job accepts.


# Logger API

Source: https://kitr.dev/packages/logger/api

Every export of `kitr/logger`, read from the published type definitions. The [guide](/packages/logger) shows them in use.

## kitr/logger

### createLogger

```ts
function createLogger(options?: LoggerOptions): Logger;
```

Create a logger without the provider, for scripts, packages and tests.

### defineConfig

```ts
const defineConfig: <const C extends LoggerOptions>(config: C) => C;
```

Types `config/logger.ts`. Returns its argument unchanged.

### loggerProvider

```ts
const loggerProvider: import("@kitr/core").KitrProvider;
```

Binds `logger` into the container from `config/logger.ts`, on the server and in the browser.
In development with devtools, every record is also mirrored to the Log panel.

### silentLogger

```ts
const silentLogger: Logger;
```

A logger that discards everything, for tests.

### Logger

```ts
interface Logger {
  /** The lowest level written. Settable at run time; children copy it when created. */
  level: LogLevel;
  /** Write at `trace`: step-by-step detail. */
  trace(msg: string, fields?: Record<string, unknown>): void;
  /** Write at `debug`: detail for development. */
  debug(msg: string, fields?: Record<string, unknown>): void;
  /** Write at `info`: something that happened. */
  info(msg: string, fields?: Record<string, unknown>): void;
  /** Write at `warn`: something odd that did not fail. */
  warn(msg: string, fields?: Record<string, unknown>): void;
  /** Write at `error`. Pass an `Error` to keep its name, message, stack and code under `err`. */
  error(msg: string | Error, fields?: Record<string, unknown>): void;
  /** Write at `fatal`. Pass an `Error` to keep its name, message, stack and code under `err`. */
  fatal(msg: string | Error, fields?: Record<string, unknown>): void;
  /** A logger that adds `bindings` to every record, optionally under another name. */
  child(bindings: Record<string, unknown>, name?: string): Logger;
  /** Run `fn`, then log `msg` at info with `durationMs`, even when it throws; returns its result. */
  time<T>(msg: string, fn: () => Promise<T>, fields?: Record<string, unknown>): Promise<T>;
}
```

A logger: one method per level, child loggers that carry fields, and timing. Bound as `logger` by the provider.

### LoggerOptions

```ts
interface LoggerOptions {
  /** The lowest level written. Default `info`. */
  level?: LogLevel;
  /** Shown as `[name]` in pretty output and as `name` in JSON. */
  name?: string;
  /** 'pretty' for terminals, 'json' for production. Default: pretty in dev, json otherwise. */
  format?: 'pretty' | 'json';
  /** Fields merged into every record (e.g. requestId). */
  bindings?: Record<string, unknown>;
  /** Where lines go. Default: console. */
  write?: (line: string, record: LogRecord) => void;
}
```

Options for `createLogger`, and the shape of `config/logger.ts`.

### LogRecord

```ts
interface LogRecord {
  /** The level it was written at. */
  level: LogLevel;
  /** When it was written, as an ISO 8601 string. */
  time: string;
  /** The logger's name, when it has one. */
  name?: string;
  /** The message, or the error's message. */
  msg: string;
  /** Bindings, fields, `err` for errors and `durationMs` from `time()`. */
  [key: string]: unknown;
}
```

One log line as an object: what `write` receives and what `json` format serialises.

### LoggerConfig

```ts
type LoggerConfig = LoggerOptions;
```

The options in `config/logger.ts`; the same as `LoggerOptions`.

### LogLevel

```ts
type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
```

A log level, lowest to highest; `silent` drops everything and is for configuration only.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Logger

Source: https://kitr.dev/packages/logger

When Ada reports that her order never shipped, the logs are where you find out why. In development you want lines you can read at a glance: a coloured level, the time, the message. In production you want one JSON object per line, so your log service can search and filter by `orderId` or `requestId`. `kitr/logger` writes both from the same calls, with levels, child loggers that carry fields, timing, and a request id on every line the server writes.

The examples on this page follow one scenario: Acme's app at `app.acme.com` ships orders, generates invoices and syncs projects, and the team (Ada, Grace and Linus) reads the logs when something goes wrong.

`kitr/logger` has no dependencies and runs on the server and in the browser. It is for lines a developer reads. To be alerted about errors with the user and the steps that led to them, use [monitoring](/packages/monitoring); to count what users do, use [analytics](/packages/analytics).

## Install

```sh
kitr add logger
```

What `kitr add` does:

- Installs `@kitr/logger`.
- Adds `'@kitr/logger'` to `packages` and `() => import('@kitr/logger')` to `providers` in `kitrrc.ts`.
- Writes `config/logger.ts` (shown in [Configure](#configure)) and regenerates `config/index.ts`.
- Adds a `## kitr: logger` section to `AGENTS.md` telling coding agents to log through `ctx.logger` or `app.container.use('logger')`, never `console.log` in server code.

`kitr add logger` adds no env variables or scripts and asks no questions. To edit `package.json` without running the package manager, pass the global flag:

```sh
kitr add logger --no-install
```

The [server](/packages/server) package requires the logger, so `kitr add server` adds it first, and the server recipe adds `LOG_LEVEL=info` to `.env.example`. Every kit with a server platform (`server`, `fullstack`, `saas`, `site`, `realtime`) already has it.

`kitr remove logger` reverses the provider, `packages` entry, dependency and `AGENTS.md` steps, and deletes `config/logger.ts`.

## Configure

`kitr add logger` writes this file:

```ts
// config/logger.ts
import { defineConfig } from 'kitr/logger'

export default defineConfig({
  name: 'app',
  level: (process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error') ?? 'info',
  // 'pretty' in dev, 'json' in production by default.
})
```

| Option | Default | Description |
| --- | --- | --- |
| `level` | `'info'` | The lowest level written: `trace`, `debug`, `info`, `warn`, `error`, `fatal` or `silent`. |
| `name` | none | Shown in brackets before each message in pretty output, and as `name` in JSON. |
| `format` | `'pretty'` unless `NODE_ENV` is `production`, then `'json'` | How each line is written. |
| `bindings` | `{}` | Fields added to every record, such as `{ region: 'eu-west-1' }`. |
| `write(line, record)` | the console | Where lines go. The default writes `error` and `fatal` to `console.error` (stderr) and the rest to `console.log` (stdout). |

| Variable | Used for |
| --- | --- |
| `LOG_LEVEL` | The level in the generated config. Added to `.env.example` by the server package as `LOG_LEVEL=info`. Also read by the server when it has to create its own logger. |

The default `format` reads `process.env.NODE_ENV`, not the app's mode. In the browser there is usually no `process`, so the default is `pretty`; set `format` explicitly if you ship logs from the browser.

## Write your first log line

In a controller, the logger is `ctx.logger`. It is a child of the app's logger that adds the request id to every line:

```ts
// server/controllers/orders_controller.ts
import type { HttpContext } from 'kitr/api'

export default class OrdersController {
  async ship({ logger, params }: HttpContext<{ id: string }>) {
    logger.info('order shipped', { orderId: params.id })
    return { orderId: params.id, status: 'shipped' }
  }
}
```

Call `POST /api/orders/1042/ship` in development and the server prints:

```
INFO  14:03:22.418 [app] order shipped {"requestId":"9b2f6c1e-4f3a-4c1d-8e7a-2b5d0c9e1f44","orderId":"1042"}
```

In production, where `NODE_ENV=production`, the same call writes one JSON object:

```json
{"level":"info","time":"2026-11-07T14:03:22.418Z","name":"app","requestId":"9b2f6c1e-4f3a-4c1d-8e7a-2b5d0c9e1f44","orderId":"1042","msg":"order shipped"}
```

The message comes first and the fields second. Keep the message fixed and put the variable parts in fields: `'order shipped'` with `{ orderId }`, not `` `order ${id} shipped` ``. Your log service can then count every `order shipped` line and filter them by `orderId`.

## Write at a level

Each level has a method. Lines below the configured `level` are dropped before they are formatted, so a `debug` call in a hot path costs almost nothing in production.

| Level | Method | Use it for |
| --- | --- | --- |
| `trace` | `logger.trace(msg, fields?)` | Step-by-step detail you only turn on while debugging one thing. |
| `debug` | `logger.debug(msg, fields?)` | Detail for development: the server's request lines, cache hits. |
| `info` | `logger.info(msg, fields?)` | Things that happened: an order shipped, a job finished. |
| `warn` | `logger.warn(msg, fields?)` | Something odd that did not fail: a slow query, a retry. |
| `error` | `logger.error(msgOrError, fields?)` | A failure someone should look at. |
| `fatal` | `logger.fatal(msgOrError, fields?)` | The process cannot continue. |

`silent` is a level for configuration only: it drops everything.

```ts
// server/services/project_service.ts
import type { KitrApp } from 'kitr/app'

export async function syncProject(app: KitrApp, projectId: string) {
  const logger = app.container.use('logger')
  logger.debug('loading project', { projectId })
  logger.warn('slow query', { projectId, ms: 1840 })
  logger.info('project synced', { projectId, tasks: 42 })
}
```

## Log an error

Pass the `Error` itself to `error()` or `fatal()`. Its message becomes `msg`, and its name, message, stack and `code` are kept under `err`:

```ts
// server/services/invoice_service.ts
import type { KitrApp } from 'kitr/app'

export async function generateInvoice(app: KitrApp, invoiceNumber: string) {
  const logger = app.container.use('logger')
  try {
    throw Object.assign(new Error('connect ECONNREFUSED 10.0.0.5:5432'), { code: 'ECONNREFUSED' })
  } catch (error) {
    logger.error(error as Error, { invoiceNumber })
    throw error
  }
}
```

In JSON that becomes:

```json
{"level":"error","time":"2026-11-07T14:05:10.002Z","name":"app","invoiceNumber":"INV-2026-007","msg":"connect ECONNREFUSED 10.0.0.5:5432","err":{"name":"Error","message":"connect ECONNREFUSED 10.0.0.5:5432","stack":"Error: connect ECONNREFUSED ...","code":"ECONNREFUSED"}}
```

Pretty output prints the stack on the lines after the message. Don't pass the error as a field (`logger.error('failed', { error })`): an `Error`'s message and stack are not enumerable, so `JSON.stringify` writes `{}`. Pass it as the first argument, or copy what you need: `{ reason: (error as Error).message }`.

The server already logs every 5xx response at `error` level with the method, path and status, so you only log errors you catch and handle yourself.

## Add fields to every line

`child(bindings, name?)` returns a logger that adds `bindings` to every record. Use it to carry an id through a piece of work instead of repeating it in every call:

```ts
// server/services/order_service.ts
import type { KitrApp } from 'kitr/app'

export async function shipOrder(app: KitrApp, orderId: string) {
  const logger = app.container.use('logger').child({ orderId }, 'orders')
  logger.info('picking items')
  logger.info('label printed', { carrier: 'DHL' })
  logger.info('order shipped')
  return { orderId, status: 'shipped' as const }
}
```

```
INFO  14:03:22.418 [orders] picking items {"orderId":"1042"}
INFO  14:03:22.419 [orders] label printed {"orderId":"1042","carrier":"DHL"}
INFO  14:03:22.420 [orders] order shipped {"orderId":"1042"}
```

A child keeps its parent's bindings and adds its own; fields passed in a call win over bindings with the same key. The `name` replaces the parent's name, and without one the child keeps the parent's. For fields every line in the process should carry, such as the region or the release, set `bindings` in `config/logger.ts`:

```ts
// config/logger.ts
import { defineConfig } from 'kitr/logger'

export default defineConfig({
  name: 'app',
  level: (process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error') ?? 'info',
  bindings: { region: process.env.FLY_REGION ?? 'local', release: process.env.RELEASE ?? 'dev' },
})
```

`level`, `time` and `msg` are reserved. A field or binding with one of those names is dropped, so a stray `{ level: 'urgent' }` cannot break filtering.

## Log during a request

On the server, every request gets its own child logger with `requestId`. The id comes from the `x-request-id` header when the caller sends one (a load balancer usually does), or is a new UUID, and it is echoed back in the response header. Grep for it to see every line one request wrote.

| Where | How |
| --- | --- |
| A controller | `ctx.logger` |
| Middleware, an action or a service during a request | `useRequest().logger`, with `useRequest` from `kitr/server` |
| Code that may run inside or outside a request | `tryUseRequest()?.logger ?? app.container.use('logger')` |

```ts
// server/services/team_service.ts
import { useRequest } from 'kitr/server'

export function inviteToTeam(teamId: string, email: string) {
  const { logger } = useRequest()
  logger.info('team invite sent', { teamId, invitee: email })
}
```

`useRequest()` throws `[kitr/server] useRequest() called outside a request.` when nothing is in flight, such as in a job or at startup.

When a request finishes, the server writes one line at `debug` level with the method, path, status, client IP and duration:

```
DEBUG 14:03:22.431 [app] POST /api/orders/1042/ship {"requestId":"9b2f6c1e-...","status":200,"ip":"127.0.0.1","durationMs":13}
```

Set `LOG_LEVEL=debug` to see these lines; at the default `info` they are dropped.

## Log outside a request

The provider binds the logger as `logger` in the container. Jobs, scripts and providers read it from there:

```ts
// server/jobs/prune_sessions.ts
import { defineJob } from 'kitr/jobs'

export const pruneSessions = defineJob('prune_sessions', {
  schedule: '0 3 * * *',
  async run(_payload, { app, jobId }) {
    const logger = app.container.use('logger').child({ jobId }, 'jobs')
    logger.info('pruning expired sessions')
  },
})
```

The server keeps the same logger as `server.logger`, after `server.boot()`. Before boot it is not set yet, because the provider registers during boot.

## Log in the browser

The provider also runs in the browser. In a component, read the logger with `useService` from [`kitr/react`](/packages/react):

```tsx
// app/features/projects/project-actions.tsx
import { useService } from 'kitr/react'

export function ArchiveProjectButton({ projectId }: { projectId: string }) {
  const logger = useService('logger')
  return (
    <button type="button" onClick={() => logger.info('project archived', { projectId })}>
      Archive
    </button>
  )
}
```

Browser lines go to the browser console. Nothing is sent to your server; to collect client-side failures, use [monitoring](/packages/monitoring).

## Time an operation

`logger.time(msg, fn, fields?)` runs an async function, logs `msg` at `info` with `durationMs` when it settles, and returns its result:

```ts
// server/services/invoice_service.ts
import type { KitrApp } from 'kitr/app'

export async function renderInvoicePdf(app: KitrApp, invoiceNumber: string) {
  const logger = app.container.use('logger').child({ invoiceNumber }, 'billing')
  const bytes = await logger.time('rendered invoice PDF', async () => new Uint8Array(48_213), {
    pages: 2,
  })
  return bytes.length
  // => 48213
}
```

```
INFO  14:07:41.006 [billing] rendered invoice PDF {"invoiceNumber":"INV-2026-007","pages":2,"durationMs":212}
```

The line is written even when the function throws, and then the error is rethrown. The line itself does not say it failed, so log the error separately when you catch it.

## Change the level at run time

`level` is a property you can set. Turn on debug output in a running process without a restart:

```ts
// server/controllers/admin_controller.ts
import type { HttpContext } from 'kitr/api'

export default class AdminController {
  async setLogLevel({ app, body }: HttpContext<{}, {}, { level: 'debug' | 'info' }>) {
    const logger = app.container.use('logger')
    logger.level = body.level
    return { level: logger.level }
  }
}
```

A child copies its parent's level when it is created. Changing the root logger affects children created afterwards, such as the next request's logger, but not children that already exist. Protect a route like this one with [auth](/packages/auth).

## Choose the output format

`pretty` is for terminals: a coloured, padded level, the time in UTC to the millisecond, `[name]`, the message, the remaining fields as dim JSON, and the stack of an error on the following lines. `json` is for log services: one `JSON.stringify(record)` per line, with keys in this order: `level`, `time` (ISO 8601), `name`, the bindings, the fields, `msg`, `err`.

Force one format everywhere, for example JSON in a staging environment that runs with `NODE_ENV=development`:

```ts
// config/logger.ts
import { defineConfig } from 'kitr/logger'

export default defineConfig({
  name: 'app',
  level: (process.env.LOG_LEVEL as 'debug' | 'info' | 'warn' | 'error') ?? 'info',
  format: process.env.LOG_FORMAT === 'json' ? 'json' : undefined,
})
```

Most hosting platforms (Fly, Render, Railway, Kubernetes) collect stdout and stderr, and parse JSON lines into searchable fields. With `json` in production you need nothing else.

## Send logs to a file or a service

`write(line, record)` replaces the console. It receives the formatted line and the record object, and runs for every line at or above the level:

```ts
// config/logger.ts
import { appendFileSync } from 'node:fs'
import { defineConfig } from 'kitr/logger'

export default defineConfig({
  name: 'app',
  format: 'json',
  write(line, record) {
    appendFileSync('storage/logs/app.log', `${line}\n`)
    if (record.level === 'error' || record.level === 'fatal') console.error(line)
  },
})
```

`write` is called synchronously from every log call, so keep it fast. To ship to an HTTP endpoint, buffer records and send them in batches:

```ts
// server/log_shipper.ts
import type { LogRecord } from 'kitr/logger'

const buffer: LogRecord[] = []

export function shipLog(_line: string, record: LogRecord) {
  buffer.push(record)
  if (buffer.length >= 100) void flushLogs()
}

export async function flushLogs() {
  const batch = buffer.splice(0)
  if (!batch.length) return
  await fetch('https://logs.acme.com/ingest', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(batch),
  }).catch(() => {
    // Never let logging take the app down.
  })
}

setInterval(flushLogs, 5_000).unref()
```

```ts
// config/logger.ts
import { defineConfig } from 'kitr/logger'
import { shipLog } from '#server/log_shipper'

export default defineConfig({ name: 'app', format: 'json', write: shipLog })
```

A `write` that throws throws out of the `logger.info()` call that triggered it, so catch inside it.

## Create a logger without the provider

`createLogger(options)` returns a logger with the same options as `config/logger.ts`. Use it in scripts, in a package of your own, or anywhere no app exists:

```ts
// scripts/import_projects.ts
import { createLogger } from 'kitr/logger'

const logger = createLogger({ name: 'import', level: 'debug' })
logger.info('importing projects', { file: 'projects.csv' })
```

`silentLogger` is a ready-made logger at level `silent` that writes nothing. Pass it where an API wants a logger and you want no output, as the server's own tests do with `createServer({ logger: silentLogger })`.

## See logs in devtools

With [devtools](/packages/devtools) installed, the provider sends a copy of every record to the devtools Log panel under the `logger` channel, so server and client lines sit in one place during development. `trace` and `debug` appear as debug entries, `fatal` as errors. The fields show as the entry's data.

While devtools is active and you have not set `write`, every line goes to `console.log`, errors included, rather than splitting errors to stderr.

## Testing

`createLogger({ write })` lets a test collect records and assert on them. To test code that reads the logger from the container, boot an app with the provider and a `write` that collects:

```ts
// test/ship_order.test.ts
import { type LogRecord, loggerProvider } from 'kitr/logger'
import { createTestApp } from 'kitr/testing'
import { describe, expect, it } from 'vitest'
import { shipOrder } from '#server/services/order_service'

describe('shipOrder', () => {
  it('logs each step with the order id', async () => {
    const records: LogRecord[] = []
    const app = await createTestApp({
      providers: [loggerProvider],
      config: {
        logger: { level: 'debug', format: 'json', write: (_line, record) => records.push(record) },
      },
    })

    await shipOrder(app, '1042')

    expect(records.map((r) => r.msg)).toEqual(['picking items', 'label printed', 'order shipped'])
    expect(records[1]).toMatchObject({
      level: 'info',
      name: 'orders',
      orderId: '1042',
      carrier: 'DHL',
    })
  })
})
```

Each record is a plain object, so assertions are on fields:

| Field | Example assertion |
| --- | --- |
| `level` | `expect(records[0]?.level).toBe('warn')` |
| `msg` | `expect(records.map((r) => r.msg)).toContain('order shipped')` |
| `name` | `expect(records[0]?.name).toBe('orders')` |
| your fields and bindings | `expect(records[0]).toMatchObject({ orderId: '1042' })` |
| `err` | `expect(records[0]?.err).toMatchObject({ code: 'ECONNREFUSED' })` |
| `durationMs` | `expect(typeof records[0]?.durationMs).toBe('number')` |

To check the exact text a line produces, assert on the first argument of `write` instead of the record. To keep a noisy test quiet, configure `level: 'silent'` or pass `silentLogger`:

```ts
// test/quiet_server.test.ts
import { silentLogger } from 'kitr/logger'
import { createServer } from 'kitr/server'
import { expect, it } from 'vitest'

it('answers the health check without printing', async () => {
  const server = createServer({ logger: silentLogger })
  const res = await server.fetch(new Request('http://localhost/healthz'))
  expect(await res.json()).toEqual({ ok: true })
})
```

## Next steps

- [Logger API reference](/packages/logger/api): every export with its signature.
- [Server](/packages/server): request ids, the request logger and error logging.
- [Monitoring](/packages/monitoring): alerts with user and breadcrumbs when something breaks.
- [Devtools](/packages/devtools): the Log panel that mirrors every line in development.
- [Jobs](/packages/jobs): what the worker logs when a job retries or fails.
- [Configuration](/docs/configuration): how `config/logger.ts` and env variables are loaded.


# Mail API

Source: https://kitr.dev/packages/mail/api

Every export of `kitr/mail`, `kitr/mail/provider`, read from the published type definitions. The [guide](/packages/mail) shows them in use.

## kitr/mail

### address

```ts
function address(input: Recipient): Address;
```

Parse a recipient (`'Ada <ada@acme.com>'`, quoted names included) into an `Address`, trimming the email.

### createLogTransport

```ts
function createLogTransport(options?: {
  print?: boolean;
}): MailTransport & {
  messages: Message[];
};
```

Keeps messages in memory (`mailer.sent`) and prints them unless `print: false`; the default
outside production. Never cleared, so not for production.

### createMailer

```ts
function createMailer(options?: CreateMailerOptions): Mailer;
```

Create a mailer without the provider, for scripts and tests. Uses the log transport when none is given.

### createResendTransport

```ts
function createResendTransport(options: {
  apiKey: string;
  fetch?: typeof fetch;
}): MailTransport;
```

Sends through Resend's HTTP API with `fetch`. A non-2xx response throws `Resend <status>: <body>`.

### createSmtpTransport

```ts
function createSmtpTransport(nodemailer: NodemailerLike | {
  default: NodemailerLike;
}, options: {
  host: string;
  port?: number;
  secure?: boolean;
  auth?: {
    user: string;
    pass: string;
  };
}): MailTransport;
```

SMTP through nodemailer (`pnpm add nodemailer`). Pass the module in so the bundler sees a real
dependency: `createSmtpTransport(nodemailer, { host, port, auth })`.

### defineMail

```ts
function defineMail<Props = Record<string, never>>(name: string, template: Omit<MailTemplate<Props>, 'name'>): MailTemplate<Props>;
```

Declare an email template. The type parameter is its props, so `send()` checks them;
the name is its preview URL.

### formatAddress

```ts
function formatAddress(a: Address): string;
```

Write an `Address` as a header value, quoting display names with commas or quotes so they stay one recipient.

### htmlToText

```ts
function htmlToText(html: string): string;
```

A readable text version of an HTML body: links become `text (url)`, block ends become line breaks. Used when a template has no `text`.

### mailPreview

```ts
function mailPreview<S extends {
  h3: {
    get(path: string, handler: (event: any) => unknown): unknown;
  };
}>(server: S, templates: MailTemplate<any>[], options?: {
  path?: string;
  mailer?: Mailer;
}): S;
```

Serves every registered template at `<previewPath>/<name>` in development (the `preview` props,
or `?prop=value` from the query string), and an index listing them.

### useMailer

```ts
function useMailer(app: KitrApp): Mailer;
```

The mailer the provider bound in this app's container. Throws in the browser, where nothing is bound.

### defineConfig

```ts
const defineConfig: <const C extends MailConfig>(config: C) => C;
```

Types `config/mail.ts`. Returns its argument unchanged.

### Address

```ts
interface Address {
  /** The address itself, such as `ada@acme.com`. */
  email: string;
  /** The display name, such as `Ada Lovelace`. */
  name?: string;
}
```

A parsed email address, as every `Message` field holds it.

### CreateMailerOptions

```ts
interface CreateMailerOptions extends MailConfig {
  /** Renders React to static HTML. Default: react-dom/server's renderToStaticMarkup. */
  renderHtml?: (element: ReactElement) => Promise<string> | string;
}
```

Options for `createMailer`: the config options plus how React is rendered.

### MailConfig

```ts
interface MailConfig {
  /** Where messages go. Unset in production, the provider refuses to boot. */
  transport?: MailTransport;
  /** Default sender. */
  from?: Recipient;
  /**
   * Meant as the preview path (default `/_kitr/mail`; false disables). Not read today:
   * `mailPreview()` takes its own `path` option.
   */
  previewPath?: string | false;
}
```

The options in `config/mail.ts`.

### Mailer

```ts
interface Mailer {
  /** Render, check and send one message; resolves with its id and transport name. */
  send<P>(template: MailTemplate<P>, props: P, options: SendOptions): Promise<SentMail>;
  /** The rendered message without sending it, for tests and previews. */
  render<P>(template: MailTemplate<P>, props: P, options?: Partial<SendOptions>): Promise<Message>;
  /** The transport messages go through. */
  readonly transport: MailTransport;
  /** Messages the log transport kept, newest last. Empty with other transports. */
  readonly sent: readonly Message[];
}
```

The service the provider binds as `mailer`: renders templates and sends them through the transport.

### MailTemplate

```ts
interface MailTemplate<Props> {
  /** Identifies the template in previews (`/_kitr/mail/<name>`). */
  name: string;
  /** The subject line, or a function of the props that returns it. */
  subject: string | ((props: Props) => string);
  /** The body as React. Plain components, or React Email's <Html>, <Button> and friends. */
  render: (props: Props) => ReactElement;
  /** A text alternative; derived from the HTML when left out. */
  text?: (props: Props) => string;
  /** Props the development preview renders with. */
  preview?: Props;
}
```

An email template made by `defineMail`: a name, a subject and a React body, typed by its props.

### MailTransport

```ts
interface MailTransport {
  /** Reported as `SentMail.transport`. */
  name: string;
  /** Deliver a finished message; throw on failure. Resolve with the provider's id when it has one. */
  send(message: Message): Promise<{
    id?: string;
  }>;
}
```

Where messages go: the log, Resend and SMTP transports, or your own object with these two members.

### Message

```ts
interface Message {
  /** The sender. */
  from: Address;
  /** The recipients; never empty once sent. */
  to: Address[];
  /** Carbon-copy recipients. */
  cc?: Address[];
  /** Blind carbon-copy recipients. */
  bcc?: Address[];
  /** Where replies go. */
  replyTo?: Address;
  /** The subject line. */
  subject: string;
  /** The full HTML document. */
  html: string;
  /** The plain-text version: the template's `text`, or derived from the HTML. */
  text: string;
  /** Extra headers, such as `List-Unsubscribe`. */
  headers?: Record<string, string>;
  /** Attached files; `content` is a string or bytes. */
  attachments?: Array<{
    filename: string;
    content: string | Uint8Array;
    contentType?: string;
  }>;
}
```

A rendered, checked message, as transports receive it and `mailer.sent` keeps it.

### NodemailerLike

```ts
interface NodemailerLike {
  /** nodemailer's `createTransport`, called once on the first send. */
  createTransport(options: unknown): {
    sendMail(message: Record<string, unknown>): Promise<{
      messageId?: string;
    }>;
  };
}
```

The part of nodemailer the SMTP transport uses; pass the module itself.

### SendOptions

```ts
interface SendOptions {
  /** One recipient or a list. Required. */
  to: Recipient | Recipient[];
  /** Carbon-copy recipients. */
  cc?: Recipient | Recipient[];
  /** Blind carbon-copy recipients. */
  bcc?: Recipient | Recipient[];
  /** Overrides `from` in `config/mail.ts` for this message. */
  from?: Recipient;
  /** Where replies go. */
  replyTo?: Recipient;
  /** Extra headers. Names must be tokens; values may not contain line breaks. */
  headers?: Record<string, string>;
  /** Files to attach: `{ filename, content, contentType? }`. */
  attachments?: Message['attachments'];
}
```

The third argument of `mailer.send()`: recipients, sender overrides, headers and attachments.

### SentMail

```ts
interface SentMail {
  /** The transport's message id, or a random UUID when it returned none. */
  id: string;
  /** The name of the transport that sent it. */
  transport: string;
}
```

What `mailer.send()` resolves with.

### Recipient

```ts
type Recipient = string | Address;
```

An address in any accepted form: `'ada@acme.com'`, `'Ada <ada@acme.com>'` or an `Address`.

## kitr/mail/provider

### mailProvider

```ts
const mailProvider: import("@kitr/core").KitrProvider;
```

Binds `mailer` from `config/mail.ts`; the log transport outside production unless one is set.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Mail

Source: https://kitr.dev/packages/mail

Order confirmations, password resets, invoices, team invites: almost every app sends email, and most end up with a folder of HTML strings nobody wants to touch. In kitr an email is a React component with a subject. `kitr/mail` renders it to HTML and plain text, checks every address and header, sends it through [Resend](https://resend.com/docs), SMTP or your own transport, and shows you a live preview of every template while you work.

The examples on this page follow one scenario: Acme's app at `app.acme.com` emails Ada Lovelace when her order ships, sends Grace an invoice as a PDF, and copies Linus on the ones he cares about.

`kitr/mail` runs on the server only. The provider binds nothing in the browser. To send without making a request wait for the mail provider, send from a [job](/packages/jobs).

## Install

```sh
kitr add mail
```

What `kitr add` does:

- Installs `@kitr/mail`. Mail requires the [server](/packages/server) package, so `kitr add` also adds `server` (and its `logger`) when the project does not have them yet.
- Adds `'@kitr/mail'` to `packages` and `() => import('@kitr/mail/provider')` to `providers` in `kitrrc.ts`.
- Adds `RESEND_API_KEY=` and `MAIL_FROM=App <hello@example.com>` under a `# Mail` comment to `.env.example`, and to `.env` when that file exists.
- Writes `config/mail.ts` (shown in [Configure](#configure)) and regenerates `config/index.ts`.
- Writes an example template, `server/mail/welcome.tsx`, exporting `welcomeMail`.
- Adds `mailPreview(server, [welcomeMail])` to `server/main.ts`, inside `if (server.app.isDevelopment)`, with its imports. This step is skipped when the project has no `server/main.ts`.
- Adds a `## kitr: mail` section to `AGENTS.md` telling coding agents where templates live and how to send them.

`kitr add mail` asks no questions. To edit `package.json` without running the package manager, pass the global flag:

```sh
kitr add mail --no-install
```

No kit includes mail; add it to any kit with a server platform (`fullstack`, `server`, `saas`, `site`, `realtime`).

`kitr remove mail` reverses the provider, `packages` entry, dependency and `AGENTS.md` steps, and deletes `config/mail.ts`. It leaves your templates in `server/mail/`, the env variables, and the `mailPreview` lines in `server/main.ts`, which you delete by hand.

## Configure

`kitr add mail` writes this file:

```ts
// config/mail.ts
import { createLogTransport, createResendTransport, defineConfig } from 'kitr/mail'

/** Development logs every message; production needs a transport: Resend here, or createSmtpTransport(nodemailer, { host, auth }). */
export default defineConfig({
  from: process.env.MAIL_FROM ?? 'App <hello@example.com>',
  transport: process.env.RESEND_API_KEY
    ? createResendTransport({ apiKey: process.env.RESEND_API_KEY })
    : createLogTransport(),
})
```

With `RESEND_API_KEY` set, messages go to Resend. Without it they go to the log transport, which prints each message to the console and keeps it in memory.

| Option | Default | Description |
| --- | --- | --- |
| `from` | none | The default sender for every message, as `'Acme <orders@acme.com>'`, `'orders@acme.com'` or `{ email, name }`. `send()` throws when neither this nor the `from` send option is set. |
| `transport` | the log transport, outside production | Where messages go. The provider refuses to boot in production when this is unset. |
| `previewPath` | `/_kitr/mail` | Declared in `MailConfig`, but `mailPreview()` does not read it today. Pass `{ path }` to `mailPreview()` to move the preview pages. |

| Variable | Used for |
| --- | --- |
| `RESEND_API_KEY` | The Resend API key. When set, the generated config sends through Resend. |
| `MAIL_FROM` | The default sender, such as `Acme <orders@acme.com>`. |

Set `MAIL_FROM` to an address on a domain you have verified with your provider. Resend and most SMTP services reject a sender on an unverified domain.

> **Warning**
> The generated config falls back to the log transport whenever `RESEND_API_KEY` is empty, in production too. The provider only refuses to boot when `transport` is unset, so a production server with a missing key boots, sends nothing, and prints every email (password reset links included) to its logs. Make production fail instead, as shown in [Send in production](#send-in-production).

## Send your first email

Generate a template:

```sh
kitr make:mail order-shipped
```

That writes `server/mail/order_shipped.tsx`. Edit it to describe the email Ada gets when her order leaves the warehouse:

```tsx
// server/mail/order_shipped.tsx
import { defineMail } from 'kitr/mail'

export interface OrderShippedProps {
  firstName: string
  orderId: string
}

export const orderShippedMail = defineMail<OrderShippedProps>('order_shipped', {
  subject: ({ orderId }) => `Order ${orderId} has shipped`,
  preview: { firstName: 'Ada', orderId: '1042' },
  render: ({ firstName, orderId }) => (
    <html lang="en">
      <body style={{ fontFamily: 'system-ui, sans-serif', lineHeight: 1.5 }}>
        <h1>Your order is on its way</h1>
        <p>Hi {firstName}, order {orderId} left our warehouse today.</p>
        <a href={`https://app.acme.com/orders/${orderId}`}>Track your order</a>
      </body>
    </html>
  ),
})
```

Send it from a controller. `ctx.app` is the request's app, and `useMailer(app)` returns the mailer the provider bound:

```ts
// server/controllers/orders_controller.ts
import type { HttpContext } from 'kitr/api'
import { useMailer } from 'kitr/mail'
import { orderShippedMail } from '#server/mail/order_shipped'

export default class OrdersController {
  async ship({ app, params }: HttpContext<{ id: string }>) {
    const sent = await useMailer(app).send(
      orderShippedMail,
      { firstName: 'Ada', orderId: params.id },
      { to: 'Ada Lovelace <ada@acme.com>' },
    )
    return sent
    // => { id: 'log-1', transport: 'log' }
  }
}
```

Register the route with `api.post('/orders/:id/ship', [OrdersController, 'ship'])` in `server/routes.ts` and call it. In development, with no `RESEND_API_KEY`, the server prints the message instead of sending it:

```
[kitr/mail] to Ada Lovelace <ada@acme.com>: Order 1042 has shipped
Your order is on its way
Hi Ada, order 1042 left our warehouse today.
Track your order (https://app.acme.com/orders/1042)
```

The props are typed from the template, so leaving out `orderId` is a type error. `send()` renders the component, builds the text version, checks every address and header, hands the message to the transport and resolves with `{ id, transport }`. Set `RESEND_API_KEY` and the same call sends a real email.

## Write a template

`defineMail(name, template)` returns a template object. The name identifies it in previews (`/_kitr/mail/order_shipped`); the type parameter is its props.

| Field | Required | Description |
| --- | --- | --- |
| `subject` | yes | A string, or a function of the props that returns one. |
| `render(props)` | yes | The body as a React element. Rendered to static HTML with `react-dom/server`. |
| `text(props)` | no | The plain-text version. Left out, it is derived from the HTML. See [Write the plain-text version](#write-the-plain-text-version). |
| `preview` | no | Props the development preview renders with. |

Templates are plain React with no hooks or state: they render once, on the server, to a string. Put shared layout in a component and reuse it across templates:

```tsx
// server/mail/layout.tsx
import type { ReactNode } from 'react'

export function AcmeLayout({ title, children }: { title: string; children: ReactNode }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <title>{title}</title>
      </head>
      <body style={{ fontFamily: 'system-ui, sans-serif', lineHeight: 1.5, color: '#111' }}>
        <table width="100%" cellPadding={0} cellSpacing={0} role="presentation">
          <tbody>
            <tr>
              <td style={{ maxWidth: 560, margin: '0 auto', padding: 24 }}>{children}</td>
            </tr>
          </tbody>
        </table>
        <p style={{ fontSize: 12, color: '#666' }}>Acme Inc. · app.acme.com</p>
      </body>
    </html>
  )
}
```

```tsx
// server/mail/invoice_ready.tsx
import { defineMail } from 'kitr/mail'
import { AcmeLayout } from './layout'

export interface InvoiceReadyProps {
  teamName: string
  invoiceNumber: string
  total: string
}

export const invoiceReadyMail = defineMail<InvoiceReadyProps>('invoice_ready', {
  subject: ({ invoiceNumber }) => `Invoice ${invoiceNumber} from Acme`,
  preview: { teamName: 'Analytical Engines', invoiceNumber: 'INV-2026-007', total: '$480.00' },
  render: ({ teamName, invoiceNumber, total }) => (
    <AcmeLayout title={`Invoice ${invoiceNumber}`}>
      <h1>Invoice {invoiceNumber}</h1>
      <p>
        The invoice for {teamName} is attached. The total is {total}.
      </p>
      <a href={`https://app.acme.com/invoices/${invoiceNumber}`}>View it online</a>
    </AcmeLayout>
  ),
})
```

Props are escaped like any React text, so a project name of `<script>` arrives as `&lt;script&gt;`. Mail clients do not load your stylesheets, so use inline `style` props. Images must be absolute URLs (`https://app.acme.com/logo.png`); `kitr/mail` has no inline (CID) attachments. When the rendered HTML does not start with `<!doctype` or `<html`, `kitr/mail` prepends `<!DOCTYPE html>`.

## Use React Email components

[React Email](https://react.email/docs/introduction) publishes components such as `<Html>`, `<Button>`, `<Container>` and `<Text>` that render to markup mail clients handle well. They are React components, so they work inside `render`:

```sh
pnpm add @react-email/components
```

```tsx
// server/mail/team_invite.tsx
import { Body, Button, Container, Html, Text } from '@react-email/components'
import { defineMail } from 'kitr/mail'

export interface TeamInviteProps {
  inviter: string
  teamName: string
  token: string
}

export const teamInviteMail = defineMail<TeamInviteProps>('team_invite', {
  subject: ({ inviter, teamName }) => `${inviter} invited you to ${teamName}`,
  preview: { inviter: 'Grace', teamName: 'Analytical Engines', token: 'tok_preview' },
  render: ({ inviter, teamName, token }) => (
    <Html lang="en">
      <Body style={{ fontFamily: 'system-ui, sans-serif' }}>
        <Container>
          <Text>
            {inviter} invited you to join {teamName} on Acme.
          </Text>
          <Button href={`https://app.acme.com/invites/${token}`}>Accept the invite</Button>
        </Container>
      </Body>
    </Html>
  ),
})
```

`kitr/mail` renders with `renderToStaticMarkup` from `react-dom/server`, not React Email's own `render()`. A component that only works through React Email's async `render()` needs a mailer you create yourself with `createMailer({ renderHtml })`; see [Create a mailer without the provider](#create-a-mailer-without-the-provider).

## Write the plain-text version

Every message has a text part, for clients that show no HTML and for spam filters that score its absence. Left out, `kitr/mail` derives it from the HTML with `htmlToText()`:

```ts
// scripts/text_preview.ts
import { htmlToText } from 'kitr/mail'

htmlToText(
  '<h1>Invoice INV-7</h1><p>Total: $40 &amp; tax</p><ul><li>Hosting</li><li>Support</li></ul><a href="https://app.acme.com/invoices/7">View invoice</a>',
)
// => 'Invoice INV-7\nTotal: $40 & tax\nHosting\nSupport\nView invoice (https://app.acme.com/invoices/7)'
```

- `<head>`, `<style>` and `<script>` are dropped with their contents.
- Links become `text (url)`.
- Closing `p`, `div`, `h1`–`h6`, `li`, `tr` and `br` become line breaks; three or more in a row collapse to one blank line.
- `&nbsp;`, `&lt;`, `&gt;`, `&quot;`, `&#39;` and `&amp;` are decoded. Other named entities (`&pound;`) stay as written.

When the derived text reads badly, usually because of layout tables, write it yourself:

```tsx
// server/mail/order_shipped.tsx
import { defineMail } from 'kitr/mail'

export const orderShippedMail = defineMail<{ firstName: string; orderId: string }>('order_shipped', {
  subject: ({ orderId }) => `Order ${orderId} has shipped`,
  text: ({ firstName, orderId }) =>
    `Hi ${firstName},\n\nOrder ${orderId} left our warehouse today.\nTrack it: https://app.acme.com/orders/${orderId}`,
  render: ({ firstName, orderId }) => (
    <p>
      Hi {firstName}, order {orderId} left our warehouse today.
    </p>
  ),
})
```

## Send an email

On the server, `useMailer(app).send(template, props, options)` sends one message. `options.to` is required; everything else is optional.

| Send option | Type | Description |
| --- | --- | --- |
| `to` | `Recipient \| Recipient[]` | Who gets it. Required; an empty list throws `No recipient`. |
| `cc`, `bcc` | `Recipient \| Recipient[]` | Copies. |
| `from` | `Recipient` | Overrides `from` in `config/mail.ts` for this message. |
| `replyTo` | `Recipient` | Where replies go. |
| `headers` | `Record<string, string>` | Extra headers, such as `List-Unsubscribe`. |
| `attachments` | `{ filename, content, contentType? }[]` | Files to attach. `content` is a string or a `Uint8Array`. |

A `Recipient` is `'ada@acme.com'`, `'Ada Lovelace <ada@acme.com>'` or `{ email: 'ada@acme.com', name: 'Ada Lovelace' }`.

`send()` resolves with a `SentMail`:

| Field | Description |
| --- | --- |
| `id` | The id the transport returned (Resend's email id, SMTP's `messageId`, `log-<n>` for the log transport), or a random UUID when it returned none. |
| `transport` | The transport's name: `log`, `resend`, `smtp` or yours. |

Store `id` next to the order when you want to match it against the provider's delivery webhooks later.

## Address several recipients

Every address field takes one recipient or a list, in any of the three forms:

```ts
// server/services/invoice_service.ts
import type { KitrApp } from 'kitr/app'
import { useMailer } from 'kitr/mail'
import { invoiceReadyMail } from '#server/mail/invoice_ready'

export async function sendInvoice(app: KitrApp) {
  return useMailer(app).send(
    invoiceReadyMail,
    { teamName: 'Analytical Engines', invoiceNumber: 'INV-2026-007', total: '$480.00' },
    {
      to: ['Grace Hopper <grace@acme.com>', { email: 'ada@acme.com', name: 'Ada Lovelace' }],
      cc: 'linus@acme.com',
      bcc: 'billing-archive@acme.com',
    },
  )
}
```

Before anything is sent, each address is parsed with `address()` and checked. You can call the same helpers yourself:

```ts
// scripts/addresses.ts
import { address, formatAddress } from 'kitr/mail'

address('Ada Lovelace <ada@acme.com>')
// => { name: 'Ada Lovelace', email: 'ada@acme.com' }
address('ada@acme.com')
// => { email: 'ada@acme.com' }
formatAddress({ name: 'Lovelace, Ada', email: 'ada@acme.com' })
// => '"Lovelace, Ada" <ada@acme.com>'
```

`formatAddress()` quotes display names that contain commas or quotes. Without the quotes, `Lovelace, Ada <ada@acme.com>` reads as two recipients. The check rejects whitespace, `<`, `>`, `,`, `;` and `"` in the address part and requires an `@`. It does not check that the domain exists: `ada@acme` passes, and your provider bounces it later.

Don't join several people into one string (`'ada@acme.com, grace@acme.com'`); it throws `is not an email address`. Pass an array.

## Set the sender and reply-to

The sender comes from `from` in `config/mail.ts`. Override it per message, and point replies at a person or a support inbox:

```ts
// server/services/support_service.ts
import type { KitrApp } from 'kitr/app'
import { useMailer } from 'kitr/mail'
import { orderShippedMail } from '#server/mail/order_shipped'

export async function sendFromSupport(app: KitrApp) {
  return useMailer(app).send(
    orderShippedMail,
    { firstName: 'Ada', orderId: '1042' },
    {
      to: 'ada@acme.com',
      from: 'Acme Support <support@acme.com>',
      replyTo: 'Linus <linus@acme.com>',
    },
  )
}
```

Without a `from` anywhere, `send()` and `render()` throw ``[kitr/mail] No sender: set `from` in config/mail.ts or in send().``

## Add headers

Pass custom headers in `headers`. The common one is `List-Unsubscribe`, which Gmail and Yahoo require for bulk mail:

```ts
// server/services/digest_service.ts
import type { KitrApp } from 'kitr/app'
import { useMailer } from 'kitr/mail'
import { invoiceReadyMail } from '#server/mail/invoice_ready'

export async function sendWithUnsubscribe(app: KitrApp, token: string) {
  return useMailer(app).send(
    invoiceReadyMail,
    { teamName: 'Analytical Engines', invoiceNumber: 'INV-2026-007', total: '$480.00' },
    {
      to: 'grace@acme.com',
      headers: {
        'List-Unsubscribe': `<https://app.acme.com/unsubscribe/${token}>`,
        'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
        'X-Acme-Invoice': 'INV-2026-007',
      },
    },
  )
}
```

Header names must be tokens (letters, digits and ``!#$%&'*+.^_`|~-``), so `X Acme` throws `Bad header name "X Acme"`.

### Header injection

A line break in an address, a display name, the subject or a header value would let a value start a new header (`Bcc: someone@else.com`) at the SMTP layer. `kitr/mail` throws before sending instead, including when the subject is built from props a user typed:

```ts
// scripts/injection.ts
import { createLogTransport, createMailer } from 'kitr/mail'
import { orderShippedMail } from '#server/mail/order_shipped'

const mailer = createMailer({ from: 'orders@acme.com', transport: createLogTransport({ print: false }) })

await mailer.send(orderShippedMail, { firstName: 'Ada', orderId: '1042\r\nBcc: someone@else.com' }, { to: 'ada@acme.com' })
// throws Error: [kitr/mail] Line break in the subject.
```

Nothing reaches the transport when a check fails.

## Attach a file

Attachments are `{ filename, content, contentType? }`. `content` is a string or bytes, so a file read with `node:fs` goes straight in:

```ts
// server/services/invoice_service.ts
import { readFile } from 'node:fs/promises'
import type { KitrApp } from 'kitr/app'
import { useMailer } from 'kitr/mail'
import { invoiceReadyMail } from '#server/mail/invoice_ready'

export async function sendInvoicePdf(app: KitrApp, invoiceNumber: string) {
  const pdf = await readFile(`storage/invoices/${invoiceNumber}.pdf`)
  return useMailer(app).send(
    invoiceReadyMail,
    { teamName: 'Analytical Engines', invoiceNumber, total: '$480.00' },
    {
      to: 'Grace Hopper <grace@acme.com>',
      attachments: [
        { filename: `${invoiceNumber}.pdf`, content: pdf, contentType: 'application/pdf' },
        { filename: 'usage.csv', content: 'project,hours\nEngines,42\n', contentType: 'text/csv' },
      ],
    },
  )
}
```

The Resend transport base64-encodes each attachment, encoding string content as UTF-8 first; large files are encoded in chunks. The SMTP transport passes attachments to nodemailer unchanged. Providers cap message size, so link to large files instead of attaching them.

## Send from a job

Sending inside a request makes the response wait for the mail provider, and a provider outage fails the request. Dispatch a [job](/packages/jobs) instead. The request returns at once, and the job retries with backoff when the provider is down:

```ts
// server/jobs/send_order_shipped.ts
import { defineJob } from 'kitr/jobs'
import { useMailer } from 'kitr/mail'
import { z } from 'zod'
import { orderShippedMail } from '#server/mail/order_shipped'

export const sendOrderShipped = defineJob('send_order_shipped', {
  schema: z.object({ orderId: z.string(), firstName: z.string(), email: z.string() }),
  retries: 5,
  backoff: 5_000,
  async run({ orderId, firstName, email }, { app }) {
    const sent = await useMailer(app).send(orderShippedMail, { firstName, orderId }, { to: email })
    return sent.id
  },
})
```

List the job in `config/jobs.ts`, then dispatch it from the controller:

```ts
// server/controllers/orders_controller.ts
import type { HttpContext } from 'kitr/api'
import { useJobs } from 'kitr/jobs'
import { sendOrderShipped } from '#server/jobs/send_order_shipped'

export default class OrdersController {
  async ship({ app, params, response }: HttpContext<{ id: string }>) {
    await useJobs(app).dispatch(sendOrderShipped, {
      orderId: params.id,
      firstName: 'Ada',
      email: 'ada@acme.com',
    })
    return response.json({ queued: true }, { status: 202 })
  }
}
```

Pass ids and plain values in the payload, not rendered HTML: the job renders the template when it runs. A message that fails a check (a bad address, a line break) throws on every attempt, so validate addresses in the job's schema, where a bad payload is rejected at dispatch.

## Render without sending

`mailer.render(template, props, options?)` builds the finished `Message` and sends nothing. Use it for snapshot tests, for storing a copy of what you sent, or to hand the message to code outside kitr:

```ts
// server/services/archive_service.ts
import type { KitrApp } from 'kitr/app'
import { useMailer } from 'kitr/mail'
import { orderShippedMail } from '#server/mail/order_shipped'

export async function renderShipped(app: KitrApp) {
  const message = await useMailer(app).render(
    orderShippedMail,
    { firstName: 'Ada', orderId: '1042' },
    { to: 'ada@acme.com' },
  )
  return message
  // => {
  //   from: { name: 'App', email: 'hello@example.com' },
  //   to: [{ email: 'ada@acme.com' }],
  //   subject: 'Order 1042 has shipped',
  //   html: '<html lang="en"><head></head><body ...',
  //   text: 'Your order is on its way\nHi Ada, order 1042 left our warehouse today.\nTrack your order (https://app.acme.com/orders/1042)',
  //   ...
  // }
}
```

`render()` runs the sender, subject, header and address checks too, but does not require a recipient: without `to` it returns `to: []`.

## Preview templates in development

`mailPreview(server, templates, options?)` serves every template in the list as a web page. The recipe adds it to `server/main.ts` for the example template. Add each new template to the list:

```ts
// server/main.ts
import { mountRoutes } from 'kitr/api'
import { mailPreview } from 'kitr/mail'
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'
import { invoiceReadyMail } from './mail/invoice_ready'
import { orderShippedMail } from './mail/order_shipped'
import { welcomeMail } from './mail/welcome'
import { routes } from './routes'

export const server = createServer({ providers: rc.providers, config })
mountRoutes(server, routes)
// Rendered templates at /_kitr/mail in development.
if (server.app.isDevelopment) mailPreview(server, [welcomeMail, orderShippedMail, invoiceReadyMail])
```

| URL | What it shows |
| --- | --- |
| `/_kitr/mail` | A list of the templates, linked by name. |
| `/_kitr/mail/order_shipped` | The HTML, rendered with the template's `preview` props. |
| `/_kitr/mail/order_shipped?orderId=2001&firstName=Grace` | The HTML, with query values replacing those props. |
| `/_kitr/mail/order_shipped?text` | The plain-text version. |
| `/_kitr/mail/missing` | `404 No such template`. |

Query values are always strings, so a template whose props are numbers or arrays only gets the right types from `preview`. Query values are escaped like any other prop.

| Option | Default | Description |
| --- | --- | --- |
| `path` | `/_kitr/mail` | Where the pages are served. |
| `mailer` | a mailer with the log transport, sender `preview@localhost` | The mailer used to render. Pass `useMailer(server.app)` to render with your real `from`. |

Keep the `isDevelopment` guard. Previews render any template with any props a visitor types into the URL.

## Use the mailer outside a request

The provider binds the mailer as `mailer` in the container, so anything with the app can reach it:

| Where | How |
| --- | --- |
| A controller | `useMailer(ctx.app)` |
| A job | `useMailer(ctx.app)` in `run(payload, ctx)` |
| An action or service during a request | `useMailer(useRequestApp())`, with `useRequestApp` from `kitr/server` |
| A script or the server file | `useMailer(server.app)` after `await server.boot()` |

`useMailer(app)` is `app.container.use('mailer')`. Called in the browser, or before the app has booted, it throws because nothing is bound.

## Transports

A transport takes a finished message and delivers it. Three are built in; each follows the same setup.

### Log

The default outside production. It prints each message's recipients, subject and text with `console.info` and keeps the message in memory, where `mailer.sent` reads it.

```ts
// config/mail.ts
import { createLogTransport, defineConfig } from 'kitr/mail'

export default defineConfig({
  from: 'Acme <orders@acme.com>',
  transport: createLogTransport({ print: false }),
})
```

| Option | Default | Description |
| --- | --- | --- |
| `print` | `true` | `false` keeps messages without printing them. |

No env variables. The kept messages are never cleared, so the list grows for as long as the process runs. Do not use it as a production transport.

### Resend

Sends through [Resend's HTTP API](https://resend.com/docs/api-reference/emails/send-email) with `fetch`. No package to install.

```ts
// config/mail.ts
import { createResendTransport, defineConfig } from 'kitr/mail'

export default defineConfig({
  from: 'Acme <orders@acme.com>',
  transport: createResendTransport({ apiKey: process.env.RESEND_API_KEY! }),
})
```

In `.env`:

```sh
RESEND_API_KEY=re_...
```

| Option | Default | Description |
| --- | --- | --- |
| `apiKey` | required | Your Resend API key. |
| `fetch` | global `fetch` | The fetch to call, for proxies or tests. |

A response that is not 2xx throws `[kitr/mail] Resend <status>: <body>`, such as `Resend 403: The acme.com domain is not verified`. The id Resend returns becomes `SentMail.id`.

### SMTP

Sends through [nodemailer](https://nodemailer.com/smtp/) to any SMTP server: Postmark, Amazon SES, Mailgun, Gmail or your own. Install nodemailer and pass the module in, so the bundler sees a real import:

```sh
pnpm add nodemailer
```

```ts
// config/mail.ts
import { createSmtpTransport, defineConfig } from 'kitr/mail'
import nodemailer from 'nodemailer'

export default defineConfig({
  from: process.env.MAIL_FROM ?? 'Acme <orders@acme.com>',
  transport: createSmtpTransport(nodemailer, {
    host: process.env.SMTP_HOST ?? 'smtp.acme.com',
    port: 587,
    auth: { user: process.env.SMTP_USER ?? '', pass: process.env.SMTP_PASS ?? '' },
  }),
})
```

In `.env`:

```sh
SMTP_HOST=smtp.postmarkapp.com
SMTP_USER=...
SMTP_PASS=...
```

| Option | Default | Description |
| --- | --- | --- |
| `host` | required | The SMTP server. |
| `port` | `587` | The port. |
| `secure` | nodemailer's default | `true` for implicit TLS, usually on port 465. |
| `auth.user`, `auth.pass` | none | Credentials. |

The connection is created on the first `send()`, not at boot, so a wrong password shows up as an error from the first email. `SentMail.id` is nodemailer's `messageId`. These env names are yours to choose; `kitr add` does not write them.

### Pick a transport per environment

Choose in `config/mail.ts` with plain conditions. This one sends through SMTP on staging, Resend in production and logs elsewhere:

```ts
// config/mail.ts
import { createLogTransport, createResendTransport, createSmtpTransport, defineConfig } from 'kitr/mail'
import nodemailer from 'nodemailer'

const transport = process.env.RESEND_API_KEY
  ? createResendTransport({ apiKey: process.env.RESEND_API_KEY })
  : process.env.SMTP_HOST
    ? createSmtpTransport(nodemailer, { host: process.env.SMTP_HOST, port: 2525 })
    : createLogTransport()

export default defineConfig({ from: 'Acme <orders@acme.com>', transport })
```

Point `SMTP_HOST` at [Mailpit](https://mailpit.axllent.org/) or a similar local inbox to see real rendered emails without sending any.

## Send in production

The provider throws `[kitr/mail] Set a transport in config/mail.ts (Resend, SMTP or your own).` at boot when the app runs in production and `transport` is unset. The generated config always sets one, so change it to leave `transport` unset in production when the key is missing:

```ts
// config/mail.ts
import { createLogTransport, createResendTransport, defineConfig } from 'kitr/mail'

const production = process.env.NODE_ENV === 'production'

export default defineConfig({
  from: process.env.MAIL_FROM ?? 'Acme <orders@acme.com>',
  transport: process.env.RESEND_API_KEY
    ? createResendTransport({ apiKey: process.env.RESEND_API_KEY })
    : production
      ? undefined
      : createLogTransport(),
})
```

Now a deploy with a missing key fails at boot instead of quietly logging emails. Before you go live:

- Verify the sending domain with your provider and set SPF, DKIM and DMARC records for it.
- Set `MAIL_FROM` to an address on that domain.
- Send from jobs, so a provider outage retries instead of failing requests.
- Keep the `mailPreview` call behind `server.app.isDevelopment`.

## Create a mailer without the provider

`createMailer(options)` returns a mailer with no app or container. Use it in scripts, in tests of a single template, or to change how React is rendered:

```ts
// scripts/send_digest.ts
import { render } from '@react-email/render'
import { createMailer, createResendTransport } from 'kitr/mail'
import { teamInviteMail } from '#server/mail/team_invite'

const mailer = createMailer({
  from: 'Acme <team@acme.com>',
  transport: createResendTransport({ apiKey: process.env.RESEND_API_KEY! }),
  renderHtml: (element) => render(element),
})

await mailer.send(teamInviteMail, { inviter: 'Grace', teamName: 'Analytical Engines', token: 'tok_1' }, { to: 'linus@acme.com' })
```

`createMailer` takes the same `from` and `transport` as `config/mail.ts`, plus `renderHtml(element)`, which returns HTML or a promise of it. The default is `renderToStaticMarkup` from `react-dom/server`. Without a `transport`, it uses the log transport.

## Errors

Every error is a plain `Error` whose message starts with `[kitr/mail]`. Nothing is sent when one is thrown.

| Message | When | What to do |
| --- | --- | --- |
| ``No sender: set `from` in config/mail.ts or in send().`` | No `from` in config or send options. | Set `from` or `MAIL_FROM`. |
| `No recipient.` | `to` is an empty list. | Pass at least one recipient. |
| `"<value>" in <field> is not an email address.` | An address is malformed, or several are joined in one string. | Pass one address per entry. |
| `Line break in <field> address.` | An address or display name contains CR or LF. | Strip line breaks from user input. |
| `Line break in the subject.` | The subject, often built from props, contains CR or LF. | Strip line breaks from the props. |
| `Bad header name "<name>".` | A header name has a space or another character not allowed in a token. | Use names like `X-Acme-Invoice`. |
| `Line break in header "<name>".` | A header value contains CR or LF. | Strip line breaks from the value. |
| `Resend <status>: <body>` | Resend answered with an error status. | Read the body: usually an unverified domain or a bad key. |
| `Set a transport in config/mail.ts (Resend, SMTP or your own).` | Boot in production with `transport` unset. | Set a transport, or the env variable that selects one. |

SMTP errors come from nodemailer unchanged.

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:mail <name>` | Writes a template to `server/mail/<snake_name>.tsx`. `--force` overwrites an existing file. |
| `kitr eject stub mail` | Copies the generator's template to `stubs/mail.ts`, so `make:mail` writes your own starting point. |

`kitr make:mail order-shipped` writes `server/mail/order_shipped.tsx`:

```tsx
// server/mail/order_shipped.tsx
import { defineMail } from 'kitr/mail'

export interface OrderShippedProps {
  firstName: string
}

/** Send with `mailer.send(orderShippedMail, props, { to })`; preview at /_kitr/mail/order_shipped in development. */
export const orderShippedMail = defineMail<OrderShippedProps>('order_shipped', {
  subject: ({ firstName }) => `OrderShipped for ${firstName}`,
  preview: { firstName: 'Ada' },
  render: ({ firstName }) => (
    <html lang="en">
      <body style={{ fontFamily: 'system-ui, sans-serif', lineHeight: 1.5 }}>
        <h1>Hello {firstName}</h1>
        <p>Replace this with the message.</p>
      </body>
    </html>
  ),
})
```

The generator does not add the template to `mailPreview()`; add it to the list in `server/main.ts`.

## Testing

Outside production the provider uses the log transport, which keeps every message. In a test, boot an app with the mail provider and a quiet log transport, run the code that sends, and read `mailer.sent`:

```ts
// test/order_shipped.test.ts
import { createLogTransport, useMailer } from 'kitr/mail'
import mailProvider from 'kitr/mail/provider'
import { createTestApp } from 'kitr/testing'
import { describe, expect, it } from 'vitest'
import { orderShippedMail } from '#server/mail/order_shipped'

describe('order shipped email', () => {
  it('sends Ada her tracking link', async () => {
    const app = await createTestApp({
      providers: [mailProvider],
      config: {
        mail: { from: 'Acme <orders@acme.com>', transport: createLogTransport({ print: false }) },
      },
    })
    const mailer = useMailer(app)

    const sent = await mailer.send(
      orderShippedMail,
      { firstName: 'Ada', orderId: '1042' },
      { to: 'Ada Lovelace <ada@acme.com>' },
    )

    expect(sent).toEqual({ id: 'log-1', transport: 'log' })
    expect(mailer.sent).toHaveLength(1)
    const message = mailer.sent[0]!
    expect(message.to).toEqual([{ name: 'Ada Lovelace', email: 'ada@acme.com' }])
    expect(message.subject).toBe('Order 1042 has shipped')
    expect(message.html).toContain('Hi Ada, order 1042 left our warehouse today.')
    expect(message.text).toContain('Track your order (https://app.acme.com/orders/1042)')
  })
})
```

`mailer.sent` is a list of `Message` objects, newest last, so the assertions you write are on plain fields:

| Field | Example assertion |
| --- | --- |
| `to`, `cc`, `bcc` | `expect(message.cc).toEqual([{ email: 'linus@acme.com' }])` |
| `from`, `replyTo` | `expect(message.from.email).toBe('orders@acme.com')` |
| `subject` | `expect(message.subject).toMatch(/1042/)` |
| `html`, `text` | `expect(message.text).toContain('https://app.acme.com/orders/1042')` |
| `headers` | `expect(message.headers?.['List-Unsubscribe']).toBeDefined()` |
| `attachments` | `expect(message.attachments?.[0]?.filename).toBe('INV-2026-007.pdf')` |

To test that nothing was sent, assert `expect(mailer.sent).toHaveLength(0)`. Each `createTestApp()` gets its own mailer, so messages do not leak between tests that boot their own app.

To test through an HTTP route, send the request with `createTestClient(server)` from `kitr/testing` and read `useMailer(server.app).sent` afterwards. The server uses your `config/mail.ts`, so its log transport prints unless you pass `print: false`.

To check a template's markup without a container, use `createMailer()` and `render()`, and snapshot the result:

```ts
// test/invoice_ready.test.ts
import { createMailer } from 'kitr/mail'
import { expect, it } from 'vitest'
import { invoiceReadyMail } from '#server/mail/invoice_ready'

it('renders the invoice email', async () => {
  const mailer = createMailer({ from: 'Acme <billing@acme.com>' })
  const message = await mailer.render(invoiceReadyMail, invoiceReadyMail.preview!, {
    to: 'grace@acme.com',
  })
  expect(message.subject).toBe('Invoice INV-2026-007 from Acme')
  expect(message.text).toMatchSnapshot()
})
```

To test your code's handling of a transport failure, pass a transport that throws:

```ts
// test/transport_failure.test.ts
import { createMailer, type MailTransport } from 'kitr/mail'
import { expect, it } from 'vitest'
import { orderShippedMail } from '#server/mail/order_shipped'

it('surfaces a provider outage', async () => {
  const down: MailTransport = {
    name: 'down',
    send: async () => {
      throw new Error('503 Service Unavailable')
    },
  }
  const mailer = createMailer({ from: 'orders@acme.com', transport: down })
  await expect(
    mailer.send(orderShippedMail, { firstName: 'Ada', orderId: '1042' }, { to: 'ada@acme.com' }),
  ).rejects.toThrow('503')
})
```

## Extend

A transport is an object with a `name` and a `send(message)` method that resolves with `{ id? }`. The `Message` it receives is final: addresses are parsed and checked, the HTML and text are rendered. See [`MailTransport`](/packages/mail/api#mailtransport) and [`Message`](/packages/mail/api#message).

```ts
// server/mail/postmark_transport.ts
import { formatAddress, type MailTransport } from 'kitr/mail'

/** Sends through Postmark's HTTP API. Attachments are left out to keep the example short. */
export function createPostmarkTransport(options: { serverToken: string }): MailTransport {
  return {
    name: 'postmark',
    async send(message) {
      const res = await fetch('https://api.postmarkapp.com/email', {
        method: 'POST',
        headers: {
          accept: 'application/json',
          'content-type': 'application/json',
          'x-postmark-server-token': options.serverToken,
        },
        body: JSON.stringify({
          From: formatAddress(message.from),
          To: message.to.map(formatAddress).join(', '),
          Cc: message.cc?.map(formatAddress).join(', '),
          Bcc: message.bcc?.map(formatAddress).join(', '),
          ReplyTo: message.replyTo ? formatAddress(message.replyTo) : undefined,
          Subject: message.subject,
          HtmlBody: message.html,
          TextBody: message.text,
          Headers: Object.entries(message.headers ?? {}).map(([Name, Value]) => ({ Name, Value })),
        }),
      })
      if (!res.ok) throw new Error(`Postmark ${res.status}: ${await res.text()}`)
      const data = (await res.json()) as { MessageID?: string }
      return { id: data.MessageID }
    },
  }
}
```

Register it in `config/mail.ts` like a built-in one:

```ts
// config/mail.ts
import { defineConfig } from 'kitr/mail'
import { createPostmarkTransport } from '#server/mail/postmark_transport'

export default defineConfig({
  from: 'Acme <orders@acme.com>',
  transport: createPostmarkTransport({ serverToken: process.env.POSTMARK_TOKEN! }),
})
```

Use `formatAddress()` whenever your transport writes an address into a string, so display names with commas stay one recipient. Throw on failure: the error reaches the caller of `send()`, and a job retries it.

Transports compose. This one falls back to a second provider when the first throws:

```ts
// server/mail/fallback_transport.ts
import type { MailTransport } from 'kitr/mail'

export function withFallback(primary: MailTransport, backup: MailTransport): MailTransport {
  return {
    name: `${primary.name}+${backup.name}`,
    async send(message) {
      try {
        return await primary.send(message)
      } catch {
        return backup.send(message)
      }
    },
  }
}
```

## Next steps

- [Mail API reference](/packages/mail/api): every export with its signature.
- [Jobs](/packages/jobs): send email in the background, with retries.
- [Server](/packages/server): the server the mailer runs in.
- [React Email](https://react.email/docs/introduction): components for email layouts.
- [Resend](https://resend.com/docs) and [nodemailer](https://nodemailer.com/): the providers behind the built-in transports.
- [Full-stack apps](/docs/fullstack): the guide to the server half of a kitr app.


# Mobile API

Source: https://kitr.dev/packages/mobile/api

Every export of `kitr/mobile`, `kitr/mobile/client`, `kitr/mobile/provider`, read from the published type definitions. The [guide](/packages/mobile) shows them in use.

## kitr/mobile

### mobile

```ts
const mobile: import("@kitr/core").PlatformFactory<MobileOptions>;
```

iOS and Android through Capacitor. The native projects live in `platforms/<name>/ios` and
`platforms/<name>/android`; the app bundle is the same client build the web platform ships.

```ts
platforms: { phone: mobile({ targets: ['ios', 'android'] }) }
kitr dev phone --target ios      # live reload on a simulator or device
kitr build phone                 # builds the web bundle and syncs it into both projects
```

### MobileOptions

```ts
interface MobileOptions {
  /** Which native projects to create and run. Default both. */
  targets: MobileTarget[];
  /** Reverse-DNS bundle id. Default `com.example.<app>`. */
  appId?: string;
  /** Name shown on the home screen. Default the package name. */
  appName?: string;
  /** Custom URL scheme for deep links (`acme://`). Recorded in kitrrc.ts; register it in the native projects yourself. */
  scheme?: string;
  /** Dev server port the device loads from with `kitr dev <name>`. Default 3100. */
  port: number;
  /** Extra Capacitor config merged last (`plugins`, `server`...). */
  capacitor?: Record<string, unknown>;
}
```

Options of the mobile platform, as written in `mobile({ ... })` in kitrrc.ts and edited by `kitr config <name>`.

### MobileTarget

```ts
type MobileTarget = 'ios' | 'android';
```

A native project the mobile platform creates and builds: `ios` (Xcode) or `android` (Android Studio).

## kitr/mobile/client

### capacitorPlatform

```ts
function capacitorPlatform(): Platform;
```

'ios' | 'android' | 'web'. Reads the global Capacitor runtime, so it is correct before any import resolves.

### isCapacitor

```ts
function isCapacitor(): boolean;
```

True inside the iOS or Android shell.

### isPluginAvailable

```ts
function isPluginAvailable(name: string): boolean;
```

True when the native shell registered the Capacitor plugin `name` (`'App'`, `'Share'`); always false on the web.

### nativeOnly

```ts
function nativeOnly<T>(fn: () => Promise<T>, fallback?: T): Promise<T | undefined>;
```

Run `fn` only inside the native shell; returns `fallback` on the web.

## kitr/mobile/provider

### preferencesDriver

```ts
function preferencesDriver(): StorageDriver;
```

`@capacitor/preferences` as a kitr storage driver: hydrated at boot, written through in the background.

### mobileProvider

```ts
const mobileProvider: import("@kitr/core").KitrProvider;
```

Runtime provider of the mobile platform. Inside the Capacitor shell it registers the
`platform` driver (App plugin: state, back button, deep links) and a `storage` driver on
Preferences, which survives the OS clearing WebView storage. In a plain browser it does nothing,
so the same bundle runs on the web.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Mobile

Source: https://kitr.dev/packages/mobile

Your customers want the app on their phone, with an icon on the home screen, the Android back button that works and data that survives the OS clearing its caches. `kitr/mobile` is the iOS and Android platform. It wraps the same `app/` you ship to the browser in a native shell, and switches the kitr packages that have a native driver (the platform hooks and storage) to it while the app runs on a phone.

It is built on [Capacitor](https://capacitorjs.com/docs): your client build runs in the system WebView, and Capacitor plugins reach native APIs. kitr adds the platform on top: `kitr dev` runs the app on a simulator with live reload, `kitr build` builds the bundle and syncs it into the Xcode and Android Studio projects, and `kitr/mobile/provider` registers the native drivers.

The provider and `kitr/mobile/client` run in the app, in the WebView and in a plain browser alike. The platform hooks (`kitr dev`, `kitr build`) run in the CLI on your machine. For an installable web app with no store listing, the PWA option of the [Web](/packages/web) platform is enough. For desktop windows, use [Desktop](/packages/desktop).

The examples on this page ship the Acme orders app to phones: Ada's field team checks orders and invoices on iPhone and Android, with the same code the browser runs at `app.acme.com`.

## Install

Add a mobile platform named `phone`:

```sh
kitr add mobile phone
```

`mobile` is the platform type and `phone` is the name you address it by (`kitr dev phone`). `kitr add mobile` with no name stops and prints `kitr add mobile <name> [--option value]   e.g. kitr add mobile phone`.

What `kitr add mobile phone` does:

- Installs `@kitr/mobile`, `@capacitor/core`, `@capacitor/app` and `@capacitor/preferences`, `@capacitor/cli` as a dev dependency, and one package per target: `@capacitor/ios` and `@capacitor/android`.
- Adds `@kitr/mobile` to `packages` in `kitrrc.ts`.
- Adds `() => import('@kitr/mobile/provider')` to `providers` in `kitrrc.ts`.
- Writes `phone: mobile({...})` into `platforms` in `kitrrc.ts`, with the flags you passed as options, and adds `import { mobile } from 'kitr/mobile'`.
- Runs the recipes the platform needs when they are missing: [Router](/packages/router) (and [React](/packages/react) before it), [Platform](/packages/platform), which writes `config/platform.ts`, and [Storage](/packages/storage), which writes `config/storage.ts` and `app/storage.ts`.
- Sets the `dev`, `build` and `start` scripts in `package.json` to `kitr dev`, `kitr build` and `kitr start`.
- Writes `platforms/phone/capacitor.config.ts` (shown under Configure) and `platforms/phone/.gitignore`, which ignores `ios/App/Pods`, `ios/App/build`, `android/build`, `android/app/build` and `android/.gradle`.
- Adds a `kitr: platform phone` section to `AGENTS.md`: how to run and build, never to sniff user agents, and to wrap other Capacitor plugins in `nativeOnly()`.

It does not create the `ios/` and `android/` projects. The first `kitr build phone` or `kitr dev phone` runs `cap add` for each target.

Platform options are flags on the same command. Option names are the flag names, in camelCase:

```sh
kitr add mobile phone --targets ios,android --appId com.acme.orders --appName "Acme Orders"
```

| Flag | Default | Effect |
| --- | --- | --- |
| `--targets` | `ios,android` | Comma-separated native projects to create. |
| `--appId` | `com.example.<app>` | Reverse-DNS bundle identifier. |
| `--appName` | the package name | Name under the home-screen icon. |
| `--scheme` | | Custom URL scheme for deep links. |
| `--port` | `3100` | Dev server port the device loads from. |
| `--no-scaffold` | | Register the platform without writing `platforms/phone/`. |
| `--no-install` | | Edit `package.json` without running the package manager. |
| `--dry-run` | | Print what would change. |

The `mobile` kit already has a `phone` platform next to a `site` web platform with `pwa: true`. Start a new project from it, picking the targets:

```sh
kitr new acme-orders --kit mobile --targets ios
```

`kitr platforms remove phone` takes the platform out of `kitrrc.ts`. It leaves `platforms/phone/`, the Capacitor packages and the provider in place; delete them yourself when you no longer ship to phones.

## Configure

`kitr/mobile` has no config file in `config/`. Its options live on the `mobile()` call in `kitrrc.ts`:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { mobile } from 'kitr/mobile'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/platform', '@kitr/storage', '@kitr/web', '@kitr/mobile'],
  providers: [
    () => import('@kitr/mobile/provider'),
    () => import('@kitr/web/provider'),
    () => import('@kitr/platform/provider'),
    () => import('@kitr/storage/provider'),
  ],
  platforms: {
    site: web({ mode: 'spa', pwa: true }),
    phone: mobile({ appId: 'com.acme.orders', appName: 'Acme Orders' }),
  },
})
```

| Option | Default | Description |
| --- | --- | --- |
| `targets` | `['ios', 'android']` | Native projects to create and build. Each must be `ios` or `android`. |
| `appId` | `com.example.<app>` | Reverse-DNS bundle identifier. The default lower-cases the app name and drops everything but letters and digits: `acme-orders` gives `com.example.acmeorders`. |
| `appName` | the package name | Name shown on the home screen. `acme-orders` becomes `Acme Orders`. |
| `scheme` | | Custom URL scheme for deep links (`acme://`). Recorded in `kitrrc.ts`; see "Open deep links" for what you register yourself. |
| `port` | `3100` | Port of the dev server the device loads with `kitr dev phone`. |
| `capacitor` | | Extra [Capacitor config](https://capacitorjs.com/docs/config), such as `plugins`, merged last into `capacitor.config.ts`. |

An unknown target fails when `kitrrc.ts` loads:

```
[kitr] Invalid options for mobile platform:
  targets: targets must be ios or android, got windows
```

The platform writes the Capacitor config next to the native projects, from the options above. With `appId: 'com.acme.orders'` and `appName: 'Acme Orders'` it is:

```ts
// platforms/phone/capacitor.config.ts
import type { CapacitorConfig } from '@capacitor/cli'

/**
 * Written by kitr from `phone: mobile({...})` in kitrrc.ts. Native projects live next to this file;
 * `kitr dev phone` sets `server.url` for live reload, `kitr build phone` syncs the built bundle.
 */
const config: CapacitorConfig = {
  appId: 'com.acme.orders',
  appName: 'Acme Orders',
  webDir: '../../dist/phone/client',
  ios: { path: 'ios' },
  android: { path: 'android' },
  ...(process.env.CAP_SERVER_URL ? { server: { url: process.env.CAP_SERVER_URL, cleartext: true } } : {}),
}

export default config
```

`webDir` points at the client build of this platform, so `kitr build phone` and `cap sync` agree on where the bundle is. The file is yours after it is written: kitr never overwrites it.

| Variable | Used for |
| --- | --- |
| `CAP_SERVER_URL` | Set by `kitr dev phone` to the dev server URL. `capacitor.config.ts` turns it into `server.url` so the app loads from your machine. Unset in builds. |
| `KITR_PHONE_<OPTION>` | Overrides one option for one run of the CLI: `KITR_PHONE_PORT=3300 kitr dev phone`, `KITR_PHONE_TARGETS=android kitr build phone`. |
| `KITR_PLATFORM` | Set to `phone` by `kitr dev` and `kitr build`, so the Vite plugin builds this platform into `dist/phone`. |

The other platform types each have their own guide and options table: [Web](/packages/web), [Server](/packages/server) and [Desktop](/packages/desktop). [Platforms](/docs/platforms) lists them side by side.

## Run the app on a phone

You need Xcode for iOS (macOS only) or Android Studio for Android, as the [Capacitor environment setup](https://capacitorjs.com/docs/getting-started/environment-setup) describes. Then add the platform and build once, which creates the native projects:

```sh
kitr add mobile phone --appId com.acme.orders --appName "Acme Orders"
kitr build phone
```

Show where the app runs on the home page:

```tsx
// app/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { usePlatform } from 'kitr/platform/react'

export const Route = createFileRoute('/')({
  component: OrdersHome,
})

function OrdersHome() {
  const platform = usePlatform()
  return (
    <main>
      <h1>Acme orders</h1>
      <p>
        Running on {platform.os}
        {platform.native ? ' in the native app' : ' in the browser'}.
      </p>
    </main>
  )
}
```

Start it on a simulator:

```sh
kitr dev phone --target ios
# phone: dev server on http://192.168.1.20:3100, the ios app loads it live
```

The iOS simulator opens Acme Orders and shows "Running on ios in the native app". The same page in a browser at `kitr dev site` says "in the browser".

## Ship the same app to the web and the phone

Both platforms build the same `app/`. Keep a web platform next to the mobile one, and each command addresses one of them or both:

```sh
kitr dev site          # the browser on port 3000
kitr dev phone         # the simulator on port 3100
kitr build             # every platform, one after another
```

Inside the shell, `kitr/mobile/provider` registers the native drivers. In a plain browser it registers nothing, so the web build of the same bundle keeps the browser behaviour. Components ask [Platform](/packages/platform) instead of checking where they run.

## Run on a simulator or device

`kitr dev phone` does four things:

1. Picks the target: `--target ios` or `--target android`. With both targets and no flag, it runs `ios` on macOS and `android` elsewhere, and says so.
2. Creates the native project with `cap add <target>` if `platforms/phone/<target>` does not exist yet.
3. Starts Vite on your machine's LAN address and the platform's port, so the device can reach it.
4. Waits for the dev server, then runs `cap run <target> --no-sync` with `CAP_SERVER_URL` set to that address.

To pick a connected device or a specific simulator, pass its id with `--device`. `npx cap run ios --list` from `platforms/phone` prints the ids:

```sh
kitr dev phone --target android --device emulator-5554
```

When the LAN address kitr picks is the wrong one (a VPN or a second network card), set the host and port yourself:

```sh
kitr dev phone --target android --host 192.168.1.20 --port 3300
```

The phone and your machine must be on the same network. `cleartext: true` in the Capacitor config lets Android load the `http://` dev server.

## Build and open the native projects

`kitr build phone` runs `vite build` into `dist/phone`, creates any missing native project, then runs `cap sync` in `platforms/phone`:

```sh
kitr build phone
# ✔ phone: synced dist/phone/client into platforms/phone/{ios,android}. Open with `pnpm exec cap open ios` from platforms/phone.
```

Pass `--open` to open each project in Xcode or Android Studio after the sync, and `--target` to build one:

```sh
kitr build phone --target ios --open
```

From the IDE you run on devices, set signing and produce the archive for the stores. The projects in `platforms/phone/ios` and `platforms/phone/android` are yours: edit `Info.plist`, `AndroidManifest.xml`, icons and splash screens there. `kitr build` only syncs the web bundle and plugin list into them.

The mobile platform has no production server, so `kitr start phone` prints `phone: the mobile platform has no start step` and returns.

## Pick the targets

Ship to one store first by listing one target:

```sh
kitr config phone targets ios
# ✔ phone.targets = ["ios"]
```

To add Android later, set both targets, install the package and build:

```sh
kitr config phone targets ios,android
pnpm add @capacitor/android
kitr build phone --target android
```

`kitr config` only edits `kitrrc.ts`. Install `@capacitor/<target>` yourself when you add one; `kitr doctor` reports it when it is missing. A `--target` the platform does not list fails with `phone has no android target (targets: ios)`.

## Set the bundle id and app name

`appId` and `appName` are written into `capacitor.config.ts` when the platform is added. Set them before the first `kitr build`, because `cap add` copies them into the native projects:

```sh
kitr config phone appId com.acme.orders
kitr config phone appName "Acme Orders"
```

`capacitor.config.ts` is written once and never overwritten, and `kitr platforms scaffold phone` skips files that exist. After changing the options, edit `appId` and `appName` in `platforms/phone/capacitor.config.ts` too, or delete the file and run `kitr platforms scaffold phone` to write it again. Once the native projects exist, change the bundle id in Xcode and in `android/app/build.gradle` as well.

## Add Capacitor plugin config

Plugin settings go in the `capacitor` option. They are merged last into the generated `capacitor.config.ts`:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { mobile } from 'kitr/mobile'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/platform', '@kitr/storage', '@kitr/mobile'],
  providers: [() => import('@kitr/mobile/provider'), () => import('@kitr/platform/provider')],
  platforms: {
    phone: mobile({
      appId: 'com.acme.orders',
      capacitor: { plugins: { SplashScreen: { launchShowDuration: 0 } } },
    }),
  },
})
```

The generated file then ends with:

```ts
// platforms/phone/capacitor.config.ts
// ...
  ...(process.env.CAP_SERVER_URL ? { server: { url: process.env.CAP_SERVER_URL, cleartext: true } } : {}),
  ...{
    "plugins": {
      "SplashScreen": {
        "launchShowDuration": 0
      }
    }
  },
}
```

Like `appId`, `capacitor` is read when the file is written. For an existing project, edit `capacitor.config.ts` directly.

## Check whether the app runs in the shell

Most code should ask [Platform](/packages/platform) (`usePlatform()`, `platform.is('ios')`). For the few places that need Capacitor itself, `kitr/mobile/client` reads the Capacitor runtime directly:

```ts
// app/features/orders/where.ts
import { capacitorPlatform, isCapacitor, isPluginAvailable } from 'kitr/mobile/client'

capacitorPlatform()
// => 'ios' on an iPhone, 'android' on Android, 'web' in a browser

isCapacitor()
// => true inside the iOS or Android shell

isPluginAvailable('App')
// => true when the native side registered the plugin
```

These read the global `Capacitor` object the native shell injects, so they are correct before any import resolves. In a browser, and on the server, they return `'web'` and `false`.

## Call a Capacitor plugin

Other Capacitor plugins are plain dependencies. Install one, sync it into the native projects, and wrap the call in `nativeOnly()` so the web build keeps working:

```sh
pnpm add @capacitor/share
kitr build phone
```

```ts
// app/features/orders/share-order.ts
import { nativeOnly } from 'kitr/mobile/client'

export async function shareOrder(order: { id: string; customer: string }) {
  const url = `https://app.acme.com/orders/${order.id}`
  const shared = await nativeOnly(async () => {
    const { Share } = await import('@capacitor/share')
    await Share.share({ title: `Order ${order.id}`, text: `${order.customer}'s order`, url })
    return 'shared' as const
  }, 'copy' as const)
  if (shared === 'copy') await navigator.clipboard.writeText(url)
  return shared
}

// => 'shared' in the shell, 'copy' in a browser
```

`nativeOnly(fn, fallback)` runs `fn` inside the shell and returns `fallback` everywhere else, without calling `fn`. Import the plugin inside `fn` so the browser bundle never evaluates it. Without a fallback it returns `undefined` on the web.

`kitr build phone` runs `cap sync`, which registers the new plugin in the native projects. A plugin you installed but did not sync makes `isPluginAvailable('Share')` return `false`.

## Handle the Android back button

On Android, `useBackButton()` from `kitr/platform/react` receives the hardware back button with `canGoBack` from the WebView history:

```tsx
// app/components/back-button.tsx
import { usePlatform, useBackButton } from 'kitr/platform/react'
import { useCallback } from 'react'

export function BackButtonHandler({ onCloseSheet }: { onCloseSheet: () => boolean }) {
  const platform = usePlatform()
  useBackButton(
    useCallback(
      ({ canGoBack }) => {
        if (onCloseSheet()) return
        if (canGoBack) window.history.back()
        else void platform.exit()
      },
      [onCloseSheet, platform],
    ),
  )
  return null
}
```

Capacitor turns off the default back behaviour as soon as a listener is registered, so the handler must go back or exit itself, as above. `platform.exit()` closes the app on Android. Wrap the handler in `useCallback`: the hook subscribes again whenever the function changes. In a browser and on iOS the handler never runs.

## Open deep links

To open `acme://orders/1042` or `https://app.acme.com/orders/1042` in the app, register the scheme or domain in the native projects, then route the URL. This release records the `scheme` option but does not write it into the native projects, so register it yourself:

- iOS: add the scheme under URL Types in Xcode (`CFBundleURLSchemes` in `Info.plist`), and Associated Domains for `https` links.
- Android: add an `intent-filter` with `<data android:scheme="acme" />` to the main activity in `AndroidManifest.xml`.

The [Capacitor deep links guide](https://capacitorjs.com/docs/guides/deep-links) has both in full. Then hand each URL to the router:

```tsx
// app/components/deep-links.tsx
import { useNavigate } from '@tanstack/react-router'
import { deepLinkPath } from 'kitr/platform'
import { useDeepLink } from 'kitr/platform/react'
import { useCallback } from 'react'

export function DeepLinks() {
  const navigate = useNavigate()
  useDeepLink(useCallback((url) => void navigate({ to: deepLinkPath(url) }), [navigate]))
  return null
}

// acme://orders/1042                      => /orders/1042
// https://app.acme.com/orders/1042?tab=invoices => /orders/1042?tab=invoices
```

The mobile driver listens to Capacitor's `appUrlOpen` event, which fires when the OS hands the app a URL while it runs. [Platform](/packages/platform) documents `deepLinkPath()` and its prefixes.

## React to the app going to the background

`useAppState()` is `true` while the app is in the foreground. Inside the shell it follows Capacitor's `appStateChange`; in a browser it follows page visibility:

```tsx
// app/features/orders/live-orders.tsx
import { useAppState } from 'kitr/platform/react'

export function LiveOrdersBadge() {
  const active = useAppState()
  return <span>{active ? 'Live' : 'Paused'}</span>
}
```

Pause polling and sockets while it is `false`, and refetch when it turns `true` again.

## Respect the notch and home indicator

`useSafeArea()` returns the insets in pixels, read from the CSS `env(safe-area-inset-*)` values. iOS reports them only when the viewport opts in, so keep `viewport-fit=cover` in the root route's viewport meta:

```tsx
// app/components/bottom-bar.tsx
import { useSafeArea } from 'kitr/platform/react'

export function BottomBar() {
  const insets = useSafeArea()
  return <nav style={{ paddingBottom: 12 + insets.bottom }}>Orders · Invoices · Teams</nav>
}
// insets on an iPhone with a notch, for example => { top: 47, right: 0, bottom: 34, left: 0 }
```

The insets are zero on the server and on the first render, then update on mount and on every resize. For layout alone, the CSS `env()` values work without the hook: `pb-[env(safe-area-inset-bottom)]`.

## Keep data in native storage

Inside the shell, `kitr/mobile/provider` registers a storage driver on [`@capacitor/preferences`](https://capacitorjs.com/docs/apis/preferences). Every `local` item from [Storage](/packages/storage) then lives in native preferences, which iOS does not clear the way it can clear WebView `localStorage`:

```ts
// app/storage.ts
import { defineStorage } from 'kitr/storage'

export const lastOrderId = defineStorage('lastOrderId', { default: '' })
```

Nothing changes in the code that reads or writes the item. The driver loads every key at boot, so reads stay synchronous, and writes go to Preferences in the background. `session` items stay in memory.

> **Warning**
> The storage provider picks its driver while it registers, so `@kitr/mobile/provider` must come before `@kitr/storage/provider` in the `providers` list of `kitrrc.ts`. With the order reversed, items stay in WebView `localStorage`, which iOS may clear, and the data is lost. `kitr add mobile` keeps the right order only when it adds storage itself; check the list when storage was already installed, and in projects made from the `mobile` kit.

## Open links in the system browser

Links to other sites should leave the app. `platform.openExternal()` opens the system browser inside the shell, and a new tab in a browser:

```tsx
// app/components/invoice-link.tsx
import { usePlatform } from 'kitr/platform/react'

export function InvoiceLink({ invoiceId }: { invoiceId: string }) {
  const platform = usePlatform()
  const url = `https://billing.acme.com/invoices/${invoiceId}`
  return (
    <button type="button" onClick={() => void platform.openExternal(url)}>
      Open invoice {invoiceId}
    </button>
  )
}
```

## Show the app version

`platform.appVersion()` resolves to the version from the native project (`CFBundleShortVersionString` on iOS, `versionName` on Android). In a browser it resolves to `'0.0.0'`:

```tsx
// app/components/about-version.tsx
import { usePlatform } from 'kitr/platform/react'
import { useEffect, useState } from 'react'

export function AboutVersion() {
  const platform = usePlatform()
  const [version, setVersion] = useState('')
  useEffect(() => {
    void platform.appVersion().then(setVersion)
  }, [platform])
  return <p>Acme Orders {version}</p>
}
// with versionName 1.4.0 => Acme Orders 1.4.0
```

## Commands

`kitr/mobile` adds no generators. The mobile platform answers these commands:

| Command | What it does |
| --- | --- |
| `kitr add mobile <name>` | Adds a mobile platform: installs Capacitor, writes `platforms.<name>`, runs the router, platform and storage recipes, writes `platforms/<name>/capacitor.config.ts`. |
| `kitr dev <name>` | Creates the native project if needed, starts Vite on the LAN and runs `cap run <target> --no-sync` against it. Flags: `--target`, `--device`, `--host`, `--port`. |
| `kitr build <name>` | Runs `vite build`, `cap add` for missing targets and `cap sync`. Flags: `--target`, `--open`. |
| `kitr config <name> [option] [value]` | Reads or sets an option in `kitrrc.ts`. `--unset` removes one. |
| `kitr platforms` | Lists every platform with its options. |
| `kitr platforms scaffold <name>` | Writes `capacitor.config.ts` and `.gitignore` when they are missing. Existing files are kept. |
| `kitr platforms remove <name>` | Takes the platform out of `kitrrc.ts`. |

Capacitor's own CLI works from `platforms/phone` for everything else: `pnpm exec cap open android`, `pnpm exec cap run ios --list`, `pnpm exec cap doctor`.

`kitr doctor` checks each mobile platform and reports:

- an error for each missing package: `@capacitor/core`, `@capacitor/cli`, `@capacitor/app`, `@capacitor/preferences` and `@capacitor/<target>`. Fix: `pnpm add <package>`.
- an error when `platforms/phone/capacitor.config.ts` is missing. Fix: `kitr platforms scaffold phone`.
- an info line for each target whose native project does not exist yet. Fix: `kitr build phone`, which runs `cap add`.

## Errors

| Message | When | What to do |
| --- | --- | --- |
| `[kitr] Invalid options for mobile platform: targets: targets must be ios or android, got windows` | `targets` lists something other than `ios` or `android`. | Use `ios`, `android` or both. |
| `phone has no ios target (targets: android)` | `--target` names a target the platform does not list. | Add it to `targets` or drop the flag. |
| `mobile has no option "<flag>" (options: targets, appId, appName, scheme, port)` | `kitr add mobile` got an unknown flag. | Use one of the listed options; names are camelCase. |
| `No platform named "<name>" in kitrrc.ts (have: site, phone)` | A command got an unknown platform name. | Use a name from `kitr platforms`. |
| `<path>/cap run android --no-sync exited with code 1` | Capacitor could not build or launch the app. kitr logs it and keeps the dev server running. | Read Capacitor's output above it; `pnpm exec cap doctor` in `platforms/phone` checks the toolchain. |
| `phone: the mobile platform has no start step` | `kitr start` ran for a mobile platform. Not an error. | Ship through Xcode or Android Studio. |

## Testing

Unit tests run in Node or `happy-dom`, where there is no Capacitor runtime. The helpers in `kitr/mobile/client` read the global `Capacitor` object, so a test sets a fake one to play the native shell and deletes it afterwards.

This test checks the platform options, that the app picks the native driver inside the shell, and that `shareOrder()` from "Call a Capacitor plugin" falls back in the browser:

```ts
// test/mobile.test.ts
import { mobileProvider } from 'kitr/mobile/provider'
import { platformProvider } from 'kitr/platform/provider'
import { createTestApp } from 'kitr/testing'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { shareOrder } from '#app/features/orders/share-order'
import rc from '../kitrrc'

function fakeShell(os: 'ios' | 'android') {
  ;(globalThis as any).Capacitor = {
    getPlatform: () => os,
    isNativePlatform: () => true,
    isPluginAvailable: () => true,
  }
}

afterEach(() => {
  delete (globalThis as any).Capacitor
})

describe('the phone platform', () => {
  it('ships Acme Orders to both stores', () => {
    expect(rc.platforms!.phone!.options).toMatchObject({
      appId: 'com.acme.orders',
      targets: ['ios', 'android'],
    })
  })

  it('uses the native driver inside the shell', async () => {
    fakeShell('android')
    const app = await createTestApp({ providers: [mobileProvider, platformProvider] })
    const platform = app.container.use('platform')
    expect(platform.type).toBe('mobile')
    expect(platform.native).toBe(true)
    expect(platform.is('android')).toBe(true)
  })

  it('keeps the browser behaviour without the shell', async () => {
    const app = await createTestApp({ providers: [mobileProvider, platformProvider] })
    expect(app.container.use('platform').native).toBe(false)
  })

  it('copies the order link in a browser', async () => {
    const writeText = vi.fn(async () => {})
    vi.stubGlobal('navigator', { clipboard: { writeText } })
    expect(await shareOrder({ id: 'ord_1042', customer: 'Ada' })).toBe('copy')
    expect(writeText).toHaveBeenCalledWith('https://app.acme.com/orders/ord_1042')
    vi.unstubAllGlobals()
  })
})
```

The fake shell is enough for the drivers kitr registers, because they reach the Capacitor plugins only when a listener or method is used. To test code that calls a plugin, mock it with `vi.mock('@capacitor/share', () => ({ Share: { share: vi.fn() } }))`. Test the real native build on a simulator or device with `kitr dev phone`.

## Next steps

- [API reference](/packages/mobile/api)
- [Platform](/packages/platform): app state, back button, deep links and safe areas on every platform
- [Storage](/packages/storage): typed items that move to native preferences on a phone
- [Web](/packages/web): the browser build of the same app, installable as a PWA
- [Platforms](/docs/platforms): every platform type and the commands they share
- [Capacitor documentation](https://capacitorjs.com/docs)


# Mocks API

Source: https://kitr.dev/packages/mocks/api

Every export of `kitr/mocks`, read from the published type definitions. The [guide](/packages/mocks) shows them in use.

## kitr/mocks

Re-exports `msw` unchanged, plus the following.

### kitrErrorResponse

```ts
function kitrErrorResponse(error: unknown): HttpResponse<import("msw").JsonBodyType>;
```

Turns anything thrown into the JSON response a kitr server sends for it: a `KitrError` keeps its
code and status, anything else becomes `INTERNAL` with status 500.

### mockRoutes

```ts
function mockRoutes(table: RouteDescriptor[], baseUrl: string, resolvers: Record<string, Resolver | unknown>): RequestHandler[];
```

MSW handlers from a kitr route table (`routes.toJSON()`) or an OpenAPI-ish list.
Unhandled routes get a 501 so a missing mock is loud, not silent.

```ts
const handlers = mockRoutes(routeTable, 'http://localhost:3000', {
  'projects.index': () => [{ id: '1', name: 'Alpha' }],
  'projects.show': ({ params }) => ({ id: params.id, name: 'Alpha' }),
})
```

### mockValidationError

```ts
function mockValidationError(method: 'post' | 'put' | 'patch', url: string, fieldErrors: Record<string, string[]>): import("msw").HttpHandler;
```

A handler that throws a kitr validation error, to test form error mapping.

### setupBrowserMocks

```ts
function setupBrowserMocks(handlers: RequestHandler[], options?: {
  quiet?: boolean;
}): Promise<import("msw/browser").SetupWorker>;
```

Starts MSW's service worker in the browser for development: `await setupBrowserMocks(handlers)`.
Needs `mockServiceWorker.js` in the public folder. Pass `quiet: false` to see MSW's console messages.

### setupNodeMocks

```ts
function setupNodeMocks(handlers: RequestHandler[]): Promise<import("msw/node").SetupServer>;
```

Starts MSW in Node for tests: `const mocks = await setupNodeMocks(handlers)`. Requests no handler
matches go to the real network. Returns MSW's server, so `use`, `resetHandlers` and `close` work.

### RouteDescriptor

```ts
interface RouteDescriptor {
  /** The route name that `mockRoutes` resolvers are keyed by, such as `orders.show`. */
  name: string;
  /** The HTTP method, in any case: `GET`, `post`. */
  method: string;
  /** The path pattern with `:params`, such as `/api/orders/:id`. */
  path: string;
}
```

One route of a kitr route table, as `routes.toJSON()` and `kitr api:sync` describe it.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Mocks

Source: https://kitr.dev/packages/mocks

Frontend work shouldn't wait for the backend. The invoices screen is designed, the API that feeds it is still a ticket, and the tests for its empty and error states need answers the real server rarely gives. `kitr/mocks` answers your app's HTTP requests with fake data: in the browser while you develop, and in Node while your tests run.

It is [Mock Service Worker](https://mswjs.io) (MSW), with `http` and `HttpResponse` re-exported unchanged. On top it adds `mockRoutes()`, which turns a kitr route table into one handler per route so you only write the answers, plus helpers that send errors in exactly the shape a kitr server sends them, so forms and error screens behave as they will in production.

It runs on the client and in tests. In the browser, a service worker intercepts `fetch`; in Node, MSW patches the global `fetch`. It cannot answer requests the server makes while rendering a page, because those never reach the browser. To test your own API routes rather than fake them, use [testing](/packages/testing)'s `createTestClient`.

The examples on this page follow Acme's billing team building the invoices screen at `app.acme.com` before the `/api/invoices` routes exist. Ada is signed in as an admin; Grace and Linus are customers.

## Install

```sh
kitr add mocks
```

What `kitr add` does:

- Adds `@kitr/mocks` to `dependencies` and `msw` to `devDependencies`, and installs them. Pass `--no-install` to skip the install.
- Adds `'@kitr/mocks'` to `packages` in `kitrrc.ts`. It registers no provider: mocks start only when your code calls them.
- Writes `app/mocks/handlers.ts` with one handler for `*/me`, unless the file exists.
- Writes `app/mocks/browser.ts`, which exports `enableMocks()`, unless the file exists.
- Adds `VITE_MOCKS=false` to `.env.example`, and to `.env` when it exists, under the comment `# Set true to serve app/mocks/handlers.ts in the browser`.
- Adds a `## kitr: mocks` section to `AGENTS.md`: handlers live in `app/mocks/handlers.ts`, `VITE_MOCKS=true` turns them on in development, tests use `setupNodeMocks(handlers)`, and a kitr route table is mocked with `mockRoutes(routes.toJSON(), baseUrl, { ... })`.

It adds no scripts, writes no config file and asks no questions. Mocks are a client package, so in a project without React `kitr add` skips it with a warning. The `app`, `desktop` and `mobile` kits include it.

`kitr add` does not copy MSW's service worker into your public folder. Do it once before you turn mocks on in the browser; see [Turn mocks on in the browser](#turn-mocks-on-in-the-browser).

`kitr remove mocks` takes `'@kitr/mocks'` out of `kitrrc.ts`, removes `@kitr/mocks` and `msw` from `package.json` and the `AGENTS.md` section, then lists files under `app/` and `config/` that still import `kitr/mocks`. It leaves `app/mocks/`, the `VITE_MOCKS` line and `public/mockServiceWorker.js` for you to delete.

## Configure

`kitr/mocks` has no config file. What you configure is the handler list and one env variable. `kitr add` writes these two files:

```ts
// app/mocks/handlers.ts
import { HttpResponse, http } from 'kitr/mocks'

export const handlers = [
  http.get('*/me', () => HttpResponse.json({ id: 'u1', email: 'dev@example.com', role: 'admin' })),
]
```

```ts
// app/mocks/browser.ts
import { setupBrowserMocks } from 'kitr/mocks'
import { handlers } from './handlers'

/** Call from main.tsx in dev: `if (import.meta.env.DEV && import.meta.env.VITE_MOCKS) await enableMocks()` */
export const enableMocks = () => setupBrowserMocks(handlers)
```

The comment in `browser.ts` is out of date: the entry file is `app/client.tsx`, and `VITE_MOCKS` is the string `'false'`, which is truthy. Compare with `=== 'true'` as shown in [Turn mocks on in the browser](#turn-mocks-on-in-the-browser).

| Variable | Used for |
| --- | --- |
| `VITE_MOCKS` | `true` serves `app/mocks/handlers.ts` in the browser during `kitr dev`. Anything else leaves the real network alone. |

The functions that start mocks take these options:

| Option | Default | Description |
| --- | --- | --- |
| `setupBrowserMocks(handlers)` | required | The handlers to serve in the browser. |
| `setupBrowserMocks(_, { quiet })` | `true` | `false` lets MSW log `[MSW] Mocking enabled` and every request it handles to the console. |
| `setupNodeMocks(handlers)` | required | The handlers to serve in Node. Starts listening immediately. |
| `mockRoutes(table)` | required | The route table: `{ name, method, path }` entries, from `routes.toJSON()` or `kitr api:sync`. |
| `mockRoutes(_, baseUrl)` | required | Prefixed to every path. `'*'` matches any origin; `'http://localhost:3333'` matches only that one. A trailing slash is removed. |
| `mockRoutes(_, _, resolvers)` | required | The answers, keyed by route name. A route without one answers `501`. |

Both setup functions start MSW with `onUnhandledFrame: 'bypass'`: a request that no handler matches goes to the real network, silently. You fake one endpoint and keep the rest.

## Fake your first endpoint

Add a handler for the request your screen makes. This one answers the invoice list with three invoices:

```ts
// app/mocks/handlers.ts
import { HttpResponse, http } from 'kitr/mocks'

export const handlers = [
  http.get('*/api/me', () =>
    HttpResponse.json({ id: 'u_ada', email: 'ada@acme.com', name: 'Ada', role: 'admin' }),
  ),
  http.get('*/api/invoices', () =>
    HttpResponse.json([
      { id: 'inv_1001', customer: 'Grace', amount: 120, status: 'paid' },
      { id: 'inv_1002', customer: 'Linus', amount: 300, status: 'open' },
      { id: 'inv_1003', customer: 'Grace', amount: 80, status: 'draft' },
    ]),
  ),
]
```

Set `VITE_MOCKS=true` in `.env`, restart `kitr dev`, and open the invoices page. The list shows the three invoices, and the browser's network panel shows each request answered `from service worker`.

The leading `*` matches any origin, so the handler answers whether your [http](/packages/http) client calls `http://localhost:3333/api/invoices` in development or `https://app.acme.com/api/invoices` in a preview. `http` and `HttpResponse` are MSW's own, so everything in [MSW's docs](https://mswjs.io/docs/http) applies.

## Turn mocks on in the browser

MSW needs its worker script served from your site's root. Copy it into `public/` once, and commit it:

```sh
npx msw init public --save
```

`--save` records the folder in `package.json`, so MSW updates the file when you upgrade it. Then start the worker in `app/client.tsx`, before the app boots, so the first request is already mocked:

```tsx
// app/client.tsx
import { StartClient } from '@tanstack/react-start/client'
import { StrictMode, startTransition } from 'react'
import { hydrateRoot } from 'react-dom/client'
import { app } from './app'

async function start() {
  if (import.meta.env.DEV && import.meta.env.VITE_MOCKS === 'true') {
    const { enableMocks } = await import('#app/mocks/browser')
    await enableMocks()
  }
  await app.boot()
  startTransition(() => {
    hydrateRoot(
      document,
      <StrictMode>
        <StartClient />
      </StrictMode>,
    )
  })
}

start()
```

The dynamic `import()` keeps MSW and your fake data out of the production bundle, and `import.meta.env.DEV` is `false` in every production build, so mocks never run there even if `VITE_MOCKS` is set.

Don't write `if (import.meta.env.VITE_MOCKS)`: env variables are strings, and `'false'` is truthy.

In a server-rendered app, the first page load renders on the server, where the browser's worker cannot see it. Loaders that fetch during that render hit the real API. Requests made after hydration, and every request in a single-page app, go through the mocks.

## Write handlers

A handler pairs a method and a URL pattern with a function that returns a response. Use `:name` for path params, read the query string from `request.url`, and read the body with `request.json()`:

```ts
// app/mocks/handlers.ts
import { HttpResponse, http } from 'kitr/mocks'

export const handlers = [
  http.get('*/api/invoices/:id', ({ params }) =>
    HttpResponse.json({ id: params.id, customer: 'Grace', amount: 120, status: 'paid' }),
  ),

  http.get('*/api/invoices', ({ request }) => {
    const status = new URL(request.url).searchParams.get('status')
    return HttpResponse.json([{ id: 'inv_1002', customer: 'Linus', amount: 300, status }])
  }),

  http.post('*/api/invoices', async ({ request }) => {
    const input = (await request.json()) as { customer: string; amount: number }
    return HttpResponse.json(
      { id: 'inv_1004', status: 'draft', ...input },
      { status: 201, headers: { location: '/api/invoices/inv_1004' } },
    )
  }),

  http.delete('*/api/invoices/:id', () => new HttpResponse(null, { status: 204 })),
]
```

`HttpResponse.json(body, init)` sets `content-type: application/json`. `HttpResponse.text()`, `HttpResponse.xml()` and a plain `new HttpResponse(body, init)` cover everything else. When two handlers match the same request, the first in the list wins.

## Keep fake data in one place

Handlers that return literal objects drift apart: the list says Grace owes 120, the detail page says 80. Put the records in one module and make the handlers read and write it, so creating an invoice makes it appear in the list:

```ts
// app/mocks/data.ts
export interface Invoice {
  id: string
  customer: string
  amount: number
  status: 'draft' | 'open' | 'paid'
}

export const invoices: Invoice[] = [
  { id: 'inv_1001', customer: 'Grace', amount: 120, status: 'paid' },
  { id: 'inv_1002', customer: 'Linus', amount: 300, status: 'open' },
  { id: 'inv_1003', customer: 'Grace', amount: 80, status: 'draft' },
]
```

```ts
// app/mocks/handlers.ts
import { HttpResponse, http } from 'kitr/mocks'
import { type Invoice, invoices } from './data'

export const handlers = [
  http.get('*/api/invoices', () => HttpResponse.json(invoices)),

  http.post('*/api/invoices', async ({ request }) => {
    const input = (await request.json()) as Pick<Invoice, 'customer' | 'amount'>
    const invoice: Invoice = { id: `inv_${1001 + invoices.length}`, status: 'draft', ...input }
    invoices.push(invoice)
    return HttpResponse.json(invoice, { status: 201 })
  }),
]
```

The array lives as long as the page, or the test file. Reload the browser and it starts over, which is usually what you want while you design.

## Mock a whole route table

With the [API](/packages/api) package, every route has a name. `mockRoutes` builds one handler per route in the table, and you write only the answers, keyed by name:

```ts
// app/mocks/handlers.ts
import { KitrError } from 'kitr/app'
import { HttpResponse, mockRoutes } from 'kitr/mocks'
import { routeTable } from '#app/api/routes.gen'
import { type Invoice, invoices } from './data'

export const handlers = mockRoutes([...routeTable], '*', {
  'invoices.index': ({ request }) => {
    const status = new URL(request.url).searchParams.get('status')
    return status ? invoices.filter((invoice) => invoice.status === status) : invoices
  },
  'invoices.show': ({ params }) => {
    const invoice = invoices.find((i) => i.id === params.id)
    if (!invoice) throw KitrError.notFound(`Invoice ${params.id}`)
    return invoice
  },
  'invoices.store': async ({ body }) => {
    const input = (await body()) as Pick<Invoice, 'customer' | 'amount'>
    const invoice: Invoice = { id: `inv_${1001 + invoices.length}`, status: 'draft', ...input }
    invoices.push(invoice)
    return HttpResponse.json(invoice, { status: 201 })
  },
  'invoices.destroy': () => undefined,
  'auth.me': { id: 'u_ada', email: 'ada@acme.com', role: 'admin' },
})
```

`routeTable` is the file `kitr api:sync` writes for the typed client: names, methods and paths, with no server code. Import it in browser mocks. In a test, `routes.toJSON()` from `#server/routes` gives the same list.

What a resolver can be, and what the request gets back:

| Resolver | Response |
| --- | --- |
| A value, not a function: `{ id: 'u_ada' }` | `200` with that value as JSON, for every request. |
| A function returning a value | `200` with the value as JSON. |
| A function returning `undefined` | `204` with no body. |
| A function returning a `Response` | That response, as is. Use it for other statuses and headers. |
| A function that throws a `KitrError` | That error's status and JSON, as the real server sends it. |
| A function that throws anything else | `500` with `code: 'INTERNAL'` and the error's message. |
| No entry for the route | `501` with `code: 'UNAVAILABLE'` and `No mock for invoices.update`. |

A resolver function receives `params` (the path params), `request` (the `Request`) and `body()`, which reads the body as JSON. An entry whose value is `undefined` counts as no entry and answers `501`; write `() => undefined` for a `204`.

The `501` is on purpose. A route you forgot to mock fails loudly with its name, instead of quietly reaching a backend that does not exist yet.

## Send an error response

Error screens are the hardest states to see in development. `kitrErrorResponse()` turns any error into the JSON response a kitr server would send, so the [http](/packages/http) client turns it back into the same `KitrError` your error handling expects:

```ts
// app/mocks/handlers.ts
import { KitrError } from 'kitr/app'
import { http, kitrErrorResponse } from 'kitr/mocks'

export const handlers = [
  http.post('*/api/invoices/:id/refund', () =>
    kitrErrorResponse(KitrError.forbidden('Only admins can refund')),
  ),
  http.get('*/api/invoices/export', () =>
    kitrErrorResponse(new KitrError('RATE_LIMITED', 'Try again in a minute')),
  ),
  http.get('*/api/ledger', () => kitrErrorResponse(new Error('Ledger offline'))),
]
```

The three responses:

```json
{ "code": "FORBIDDEN", "message": "Only admins can refund", "status": 403 }
{ "code": "RATE_LIMITED", "message": "Try again in a minute", "status": 429 }
{ "code": "INTERNAL", "message": "Ledger offline", "status": 500 }
```

A `KitrError` keeps its code, message, status, `fieldErrors` and `data`. Anything else becomes `INTERNAL` with status `500` and its message. Inside `mockRoutes`, throwing does the same thing without the call.

## Show server validation errors in a form

`mockValidationError(method, url, fieldErrors)` answers with a `422` validation error. It is the quickest way to check that a form shows the server's messages under the right fields:

```ts
// app/mocks/handlers.ts
import { mockValidationError } from 'kitr/mocks'

export const handlers = [
  mockValidationError('post', '*/api/invoices', {
    customer: ['Customer is required'],
    amount: ['Amount must be greater than 0'],
  }),
]
```

```json
{
  "code": "VALIDATION",
  "message": "Validation failed",
  "status": 422,
  "fieldErrors": {
    "customer": ["Customer is required"],
    "amount": ["Amount must be greater than 0"]
  }
}
```

`method` is `'post'`, `'put'` or `'patch'`. With [forms](/packages/forms), each message appears under its field when the submit rejects. Keys can be nested paths such as `'lines.0.amount'`.

## Simulate a slow or failed request

Loading spinners and retry buttons need slow and broken responses. MSW's `delay` pauses a handler; `HttpResponse.error()` makes `fetch` reject as if the network were down. Import `delay` from `msw` itself, which `kitr add mocks` installed:

```ts
// app/mocks/handlers.ts
import { HttpResponse, http } from 'kitr/mocks'
import { delay } from 'msw'
import { invoices } from './data'

export const handlers = [
  http.get('*/api/invoices', async () => {
    await delay(1500)
    return HttpResponse.json(invoices)
  }),
  http.get('*/api/invoices/:id/pdf', () => HttpResponse.error()),
]
```

`delay()` with no argument waits a short, realistic random time; `delay('infinite')` never answers, for testing a spinner. A `fetch` to the PDF route rejects instead of resolving, so the code path for a dropped connection runs.

## Mock a third-party API

Handlers match full URLs too, so the same file fakes services you don't own. This stands in for a currency API the invoice screen calls directly from the browser:

```ts
// app/mocks/handlers.ts
import { HttpResponse, http } from 'kitr/mocks'

export const handlers = [
  http.get('https://api.exchangerate.host/latest', ({ request }) => {
    const base = new URL(request.url).searchParams.get('base') ?? 'EUR'
    return HttpResponse.json({ base, rates: { USD: 1.08, GBP: 0.85 } })
  }),
]
```

Requests to any other host go to the real network.

## Use mocks in tests

In a test, `setupNodeMocks(handlers)` starts MSW in Node and returns MSW's server. Start it once per file, reset per-test overrides after each test, and close it at the end:

```ts
// app/features/invoices/invoices.test.ts
import { setupNodeMocks } from 'kitr/mocks'
import { afterAll, afterEach, beforeAll, expect, it } from 'vitest'
import { handlers } from '#app/mocks/handlers'

let mocks: Awaited<ReturnType<typeof setupNodeMocks>>
beforeAll(async () => {
  mocks = await setupNodeMocks(handlers)
})
afterEach(() => mocks.resetHandlers())
afterAll(() => mocks.close())

it('lists open invoices', async () => {
  const res = await fetch('https://app.acme.com/api/invoices?status=open')
  expect(await res.json()).toEqual([
    { id: 'inv_1002', customer: 'Linus', amount: 300, status: 'open' },
  ])
})
```

Any code that calls `fetch` sees the mocks: your components, the query cache, the http client. Under `happy-dom` a relative URL such as `/api/invoices` resolves against `http://localhost:3000`, which `*/api/invoices` matches. In the `node` environment there is no page URL, so use absolute URLs there.

To render a component against these mocks, combine them with `renderWithKitr` from [testing](/packages/testing#fake-the-network-for-components).

## Override a handler for one test

`mocks.use()` puts handlers in front of the list until the next `resetHandlers()`. Use it to give one test the empty state or the error it needs, without touching the shared handlers:

```ts
// app/features/invoices/invoices.test.ts
import { KitrError } from 'kitr/app'
import { HttpResponse, http, kitrErrorResponse, setupNodeMocks } from 'kitr/mocks'
import { afterAll, afterEach, beforeAll, expect, it } from 'vitest'
import { handlers } from '#app/mocks/handlers'

let mocks: Awaited<ReturnType<typeof setupNodeMocks>>
beforeAll(async () => {
  mocks = await setupNodeMocks(handlers)
})
afterEach(() => mocks.resetHandlers())
afterAll(() => mocks.close())

it('shows the empty state', async () => {
  mocks.use(http.get('*/api/invoices', () => HttpResponse.json([])))
  expect(await (await fetch('/api/invoices')).json()).toEqual([])
})

it('shows the permission error', async () => {
  mocks.use(http.get('*/api/invoices', () => kitrErrorResponse(KitrError.forbidden())))
  const res = await fetch('/api/invoices')
  expect(res.status).toBe(403)
})

it('is back to the shared handlers', async () => {
  expect((await fetch('/api/invoices')).status).toBe(200)
})
```

Don't call `setupNodeMocks` inside each test. Start it once in `beforeAll` and override with `use()`, so every test starts from the same handlers. MSW's [server API](https://mswjs.io/docs/api/setup-server) documents `use`, `resetHandlers`, `restoreHandlers` and `listHandlers`.

## Turn mocks off

Set `VITE_MOCKS=false` in `.env` and restart `kitr dev`. The next page load starts no worker, and the real API answers. To mock one endpoint and use the real backend for the rest, keep `VITE_MOCKS=true` and delete every other handler: unmatched requests always go to the network.

Production builds never start the worker, because the check in `app/client.tsx` requires `import.meta.env.DEV`.

## Errors

The responses `kitr/mocks` builds itself:

| Code | When | What to do |
| --- | --- | --- |
| `UNAVAILABLE` (501) | `mockRoutes` got a request for a route with no resolver: `No mock for invoices.update`. | Add a resolver under that route name, or remove the route from the table you pass. |
| `INTERNAL` (500) | A resolver threw something that is not a `KitrError`, or `kitrErrorResponse` got a plain error. | Throw a `KitrError` with the code you mean, or fix the resolver. |
| `VALIDATION` (422) | `mockValidationError` answered. | Expected: the form should show `fieldErrors`. |

When the browser shows `Failed to register a ServiceWorker` or a 404 for `/mockServiceWorker.js`, the worker file is missing. Run `npx msw init public --save`.

## Testing

Your handlers are the contract the frontend is built against, so test them like code. This test starts the real `app/mocks/handlers.ts` in Node and checks the answers the invoices screen relies on, including that creating an invoice makes it show up in the list:

```ts
// app/mocks/handlers.test.ts
import { setupNodeMocks } from 'kitr/mocks'
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { handlers } from './handlers'

const api = 'https://app.acme.com/api'
let mocks: Awaited<ReturnType<typeof setupNodeMocks>>

beforeAll(async () => {
  mocks = await setupNodeMocks(handlers)
})
afterAll(() => mocks.close())

describe('invoice mocks', () => {
  it('filters the list by status', async () => {
    const res = await fetch(`${api}/invoices?status=draft`)
    expect(await res.json()).toEqual([
      { id: 'inv_1003', customer: 'Grace', amount: 80, status: 'draft' },
    ])
  })

  it('answers 404 in the kitr error shape', async () => {
    const res = await fetch(`${api}/invoices/inv_9999`)
    expect(res.status).toBe(404)
    expect(await res.json()).toEqual({
      code: 'NOT_FOUND',
      message: 'Invoice inv_9999 not found',
      status: 404,
    })
  })

  it('adds a created invoice to the list', async () => {
    const created = await fetch(`${api}/invoices`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ customer: 'Ada', amount: 45 }),
    })
    expect(created.status).toBe(201)
    expect(await created.json()).toEqual({
      id: 'inv_1004',
      status: 'draft',
      customer: 'Ada',
      amount: 45,
    })

    const list = (await (await fetch(`${api}/invoices`)).json()) as Array<{ id: string }>
    expect(list.map((invoice) => invoice.id)).toContain('inv_1004')
  })

  it('fails loudly for a route nobody mocked', async () => {
    const res = await fetch(`${api}/invoices/inv_1001`, { method: 'PATCH', body: '{}' })
    expect(res.status).toBe(501)
    expect(await res.json()).toMatchObject({ message: 'No mock for invoices.update' })
  })
})
```

The test uses the `mockRoutes` handlers from [Mock a whole route table](#mock-a-whole-route-table). Because they read `app/mocks/data.ts`, the third test's invoice stays in the list for the rest of the file; Vitest gives each file a fresh copy.

## Next steps

- [API reference](/packages/mocks/api): every export of `kitr/mocks`.
- [MSW docs](https://mswjs.io/docs): handlers, response helpers, GraphQL and WebSocket mocking.
- [Testing](/packages/testing): `createTestApp`, `renderWithKitr` and the API test client.
- [API](/packages/api): route names and `kitr api:sync`, which feed `mockRoutes`.
- [HTTP](/packages/http): the client that turns these responses back into `KitrError`s.


# Monitoring API

Source: https://kitr.dev/packages/monitoring/api

Every export of `kitr/monitoring`, `kitr/monitoring/provider`, `kitr/monitoring/server`, read from the published type definitions. The [guide](/packages/monitoring) shows them in use.

## kitr/monitoring

### consoleReporter

```ts
function consoleReporter(): Reporter;
```

Prints exceptions and messages to the console; ignores breadcrumbs and users. The provider's default in development.

### createMonitoring

```ts
function createMonitoring(config?: MonitoringConfig): Monitoring;
```

Create the monitoring service without the provider: for server-only apps, scripts and tests.
Unlike the provider it adds no console reporter and no `environment` tag.

### defaultShouldReport

```ts
function defaultShouldReport(error: unknown): boolean;
```

The default `shouldReport`: drops kitr errors below 500 (client mistakes) and `AbortError`s; reports everything else.

### devtoolsReporter

```ts
function devtoolsReporter(hub: {
  log(channel: string, label: string, data?: unknown, level?: 'debug' | 'info' | 'warn' | 'error'): void;
}): Reporter;
```

Mirrors reports into the kitr devtools (channel "errors"). Added automatically in development.

### installGlobalHandlers

```ts
function installGlobalHandlers(monitoring: Monitoring): () => void;
```

Report uncaught errors and unhandled rejections in the browser (`source: 'window'`). Returns a function that removes the handlers.

### memoryReporter

```ts
function memoryReporter(): Reporter & {
  exceptions: Array<{
    error: unknown;
    context?: CaptureContext;
  }>;
  messages: string[];
  user: MonitoringUser | null;
};
```

Keeps exceptions, message texts and the last user in arrays, for tests. Ignores breadcrumbs and tags.

### sentry

```ts
function sentry(Sentry: SentryLike, options: {
  dsn: string;
  environment?: string;
  release?: string;
  tracesSampleRate?: number;
  [key: string]: unknown;
}): Reporter;
```

Sentry reporter. Pass the SDK module so the right one (react, browser, node) is bundled
for the environment: `sentry(Sentry, { dsn })`.

### defineConfig

```ts
const defineConfig: <const C extends MonitoringConfig>(config: C) => C;
```

Types `config/monitoring.ts`. Returns its argument unchanged.

### Breadcrumb

```ts
interface Breadcrumb {
  /** A group, such as `import`, `navigation` or `api`. */
  category?: string;
  /** What happened. */
  message: string;
  /** How notable the step is. */
  level?: Severity;
  /** Extra data for the step. */
  data?: Record<string, unknown>;
  /** Milliseconds since the epoch; set to `Date.now()` when left out. */
  timestamp?: number;
}
```

A step on the way to a possible error, attached to later reports by reporters that keep them.

### CaptureContext

```ts
interface CaptureContext {
  /** Short strings to filter by; merged over the config `tags`. */
  tags?: Record<string, string>;
  /** Any data that helps fix it: ids, sizes, the failing input. */
  extra?: Record<string, unknown>;
  /** How serious it is. */
  level?: Severity;
  /** Where it came from: 'error-boundary' | 'router' | 'server' | 'window' | 'action'. */
  source?: string;
}
```

The optional second argument of `captureException` and `captureMessage`.

### Monitoring

```ts
interface Monitoring {
  /** Report an error, unless `shouldReport` drops it. */
  captureException(error: unknown, context?: CaptureContext): void;
  /** Report a message. Not filtered by `shouldReport`. */
  captureMessage(message: string, context?: CaptureContext): void;
  /** Attach the signed-in user to later reports; null on sign-out. */
  setUser(user: MonitoringUser | null): void;
  /** Record a step leading up to a possible error. */
  addBreadcrumb(crumb: Breadcrumb): void;
  /** Set a tag on reporters that keep their own scope, such as Sentry. */
  setTag(key: string, value: string): void;
  /** Run `fn`, report and rethrow on failure. */
  wrap<T>(fn: () => T, context?: CaptureContext): T;
  /** Wait for every reporter to send what it queued, up to the timeout (default 2000 ms). Never throws. */
  flush(timeoutMs?: number): Promise<void>;
  /** The reporters in use. */
  readonly reporters: readonly Reporter[];
}
```

The service bound as `monitoring`: report errors and messages, and set the user, tags and breadcrumbs, on every reporter.

### MonitoringConfig

```ts
interface MonitoringConfig {
  /** Where reports go. The provider falls back to the console reporter in development. */
  reporters?: Reporter[];
  /** Return false to drop an error (expected 4xx, cancelled requests). Default drops kitr errors with status < 500. */
  shouldReport?: (error: unknown, context?: CaptureContext) => boolean;
  /** Capture `window.onerror` and unhandled rejections on the client. Default true. */
  globalHandlers?: boolean;
  /** Release / environment tags applied to every report. */
  tags?: Record<string, string>;
  /** Log to the console as well. Default: development. */
  debug?: boolean;
}
```

The options in `config/monitoring.ts`.

### MonitoringUser

```ts
interface MonitoringUser {
  /** Your id for the user. */
  id: string;
  /** The user's email, if your privacy policy allows sending it. */
  email?: string;
  /** A display or login name. */
  username?: string;
  [key: string]: unknown;
}
```

The signed-in user attached to reports by `setUser`. Any extra fields go to the reporter as-is.

### Reporter

```ts
interface Reporter {
  /** Identifies the reporter, such as `sentry`. */
  name: string;
  /** Called once when the monitoring service is created. */
  init?(): void | Promise<void>;
  /** Send an exception; must not throw or block. */
  captureException(error: unknown, context?: CaptureContext): void;
  /** Send a message that is not an exception. */
  captureMessage?(message: string, context?: CaptureContext): void;
  /** Attach the user to later reports, or clear it with null. */
  setUser?(user: MonitoringUser | null): void;
  /** Record a step for later reports. */
  addBreadcrumb?(crumb: Breadcrumb): void;
  /** Set a tag on later reports. */
  setTag?(key: string, value: string): void;
  /** Wait for queued reports to be sent, up to the timeout; resolves false when it ran out. */
  flush?(timeoutMs?: number): Promise<boolean>;
}
```

A destination for reports (Sentry, the console, your own endpoint). Only `name` and `captureException` are required.

### SentryLike

```ts
interface SentryLike {
  /** `Sentry.init`, called with the reporter's options. */
  init?(options: Record<string, unknown>): unknown;
  /** `Sentry.captureException`. */
  captureException(error: unknown, context?: Record<string, unknown>): unknown;
  /** `Sentry.captureMessage`. */
  captureMessage(message: string, context?: Record<string, unknown>): unknown;
  /** `Sentry.setUser`. */
  setUser(user: Record<string, unknown> | null): void;
  /** `Sentry.addBreadcrumb`. */
  addBreadcrumb(crumb: Record<string, unknown>): void;
  /** `Sentry.setTag`. */
  setTag(key: string, value: string): void;
  /** `Sentry.flush`. */
  flush?(timeout?: number): Promise<boolean>;
}
```

The subset of `@sentry/react` / `@sentry/browser` / `@sentry/node` these reporters call.

### Severity

```ts
type Severity = 'fatal' | 'error' | 'warning' | 'info' | 'debug';
```

How serious a report or breadcrumb is, using Sentry's levels.

## kitr/monitoring/provider

### MonitoringErrorBoundary

```ts
class MonitoringErrorBoundary extends Component<ErrorBoundaryProps, {
  error: unknown;
}> {
  state: {
    error: unknown;
  };
  static getDerivedStateFromError(error: unknown): {
    error: unknown;
  };
  private report;
  componentDidCatch(error: unknown, info: ErrorInfo): void;
  reset: () => void;
  render(): ReactNode;
}
```

Reports render errors, then shows `fallback` (or nothing, so the router's error component takes over).

### monitoringProvider

```ts
const monitoringProvider: import("@kitr/core").KitrProvider;
```

Binds `monitoring` from `config/monitoring.ts`, installs window handlers on the client,
and wraps the tree in an error boundary that reports before TanStack Router's error
component renders.

### ErrorBoundaryProps

```ts
interface ErrorBoundaryProps {
  /** The service to report render errors to. */
  monitoring: Monitoring;
  /** Shown instead of the children after an error; a function gets the error and `reset`. Left out, the boundary rethrows. */
  fallback?: ReactNode | ((error: unknown, reset: () => void) => ReactNode);
  /** What the boundary guards. */
  children: ReactNode;
}
```

Props of `MonitoringErrorBoundary`.

## kitr/monitoring/server

### reportErrors

```ts
function reportErrors(monitoring: Monitoring): (event: {
  req: {
    method: string;
    url: string;
  };
  context?: Record<string, any>;
}, next: () => Promise<unknown> | unknown) => Promise<unknown>;
```

h3 middleware that reports thrown errors (after the request context exists), then rethrows
so kitr's error handler still produces the response. `server.use(reportErrors(monitoring))`.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Monitoring

Source: https://kitr.dev/packages/monitoring

When something breaks in production, you want to know before a user writes in, and you want enough context to fix it: who it happened to, which page they were on and what they did beforehand. `kitr/monitoring` catches render errors, uncaught errors and failed server requests, adds the signed-in user, tags and breadcrumbs, and sends each report to [Sentry](https://docs.sentry.io/platforms/javascript/) or any other service through one small API.

The examples on this page follow one scenario: Acme's app at `app.acme.com`, where Ada imports projects from a CSV file, Grace manages her team's invoices, and Linus is on call when a report comes in.

`kitr/monitoring` runs in the browser and on the server. The provider and its error boundary need React; a server-only project uses the same API without the provider. It is for failures someone should fix. For lines a developer reads while debugging, use the [logger](/packages/logger); for counting what users do, use [analytics](/packages/analytics).

## Install

```sh
kitr add monitoring
```

What `kitr add` does depends on whether the project has React. In a project with React (every kit with a web platform):

- Installs `@kitr/monitoring`.
- Adds `'@kitr/monitoring'` to `packages` and `() => import('@kitr/monitoring/provider')` to `providers` in `kitrrc.ts`.
- Declares `VITE_SENTRY_DSN: e.string({ optional: true })` under `public` in `app/env.ts`, and adds `VITE_SENTRY_DSN=` to `.env.example` (and `.env` when it exists).
- Writes `config/monitoring.ts` for the browser (shown in [Configure](#configure)) and regenerates `config/index.ts`.
- Adds a `## kitr: monitoring` section to `AGENTS.md`: what is reported automatically, how to report caught errors, `setUser` on sign-in and sign-out, and the server middleware.

In a server-only project (the `server` kit, or any project with the server package and no React):

- Installs `@kitr/monitoring`.
- Adds `'@kitr/monitoring'` to `packages` in `kitrrc.ts`. It adds no provider, because the provider imports React. See [Report server errors](#report-server-errors) for the two lines that replace it.
- Adds `SENTRY_DSN=` under a `# Monitoring` comment to `.env.example` (and `.env` when it exists).
- Writes `config/monitoring.ts` for the server and regenerates `config/index.ts`.
- Adds a `## kitr: monitoring` section to `AGENTS.md` about the server middleware and `captureException`.

`kitr add monitoring` asks no questions. To edit `package.json` without running the package manager, pass the global flag:

```sh
kitr add monitoring --no-install
```

The `saas` kit includes monitoring.

`kitr remove monitoring` reverses the provider, `packages` entry, dependency and `AGENTS.md` steps, and deletes `config/monitoring.ts`. The env variable and its `app/env.ts` entry stay.

## Configure

In a project with React, `kitr add monitoring` writes this file:

```ts
// config/monitoring.ts
import { defineConfig } from 'kitr/monitoring'
import { env } from '#app/env'

/**
 * Reporters: development prints to the console, production sends nowhere until one is added.
 * Pass the SDK module so the right flavour (react, browser, node) is bundled for the environment.
 */
export default defineConfig({
  reporters: [
    // import * as Sentry from '@sentry/react'  (pnpm add @sentry/react)
    // ...(env.VITE_SENTRY_DSN ? [sentry(Sentry, { dsn: env.VITE_SENTRY_DSN })] : []),
  ],
  // shouldReport: (error) => !(error instanceof KitrError && error.status < 500),
  tags: { app: env.VITE_APP_NAME },
})
```

In a server-only project it writes this one, with `service` set to the `name` in your `package.json`:

```ts
// config/monitoring.ts
import { defineConfig } from 'kitr/monitoring'

/** Reporters: development prints to the console, production sends nowhere until one is added. */
export default defineConfig({
  reporters: [
    // import * as Sentry from '@sentry/node'  (pnpm add @sentry/node)
    // ...(process.env.SENTRY_DSN ? [sentry(Sentry, { dsn: process.env.SENTRY_DSN })] : []),
  ],
  tags: { service: 'acme-api' },
})
```

| Option | Default | Description |
| --- | --- | --- |
| `reporters` | `[]` | Where reports go. With none, the provider uses the console reporter in development and nothing in production. |
| `shouldReport(error, context)` | `defaultShouldReport` | Return `false` to drop an error. The default drops kitr errors with a status below 500 and `AbortError`s. Applies to `captureException` only. |
| `globalHandlers` | `true` | In the browser, report uncaught errors and unhandled promise rejections. |
| `tags` | none | Tags added to every exception and message. The provider adds `environment` (the app's mode: `development`, `production` or `test`) under yours. |
| `debug` | `true` in development | Also print each exception and message to the console with a `[monitoring]` prefix. |

| Variable | Used for |
| --- | --- |
| `VITE_SENTRY_DSN` | The Sentry DSN in a project with React. Public, because the browser sends reports. |
| `SENTRY_DSN` | The Sentry DSN in a server-only project. |

Neither variable does anything until you uncomment the reporter line. Until then, development prints errors to the console and [devtools](/packages/devtools), and production sends them nowhere.

## Report your first error

Errors you catch and handle are not reported unless you say so. In a component, read the service with `useService('monitoring')` and call `captureException` in the `catch`:

```tsx
// app/features/projects/import-projects-button.tsx
import { useService } from 'kitr/react'

export function ImportProjectsButton({ file }: { file: File }) {
  const monitoring = useService('monitoring')

  async function importProjects() {
    try {
      const res = await fetch('/api/projects/import', { method: 'POST', body: file })
      if (!res.ok) throw new Error(`Import failed with ${res.status}`)
    } catch (error) {
      monitoring.captureException(error, { extra: { fileName: file.name, size: file.size } })
      alert('That file could not be imported.')
    }
  }

  return (
    <button type="button" onClick={importProjects}>
      Import projects
    </button>
  )
}
```

Make the import fail in development and the browser console shows the report twice, once from `debug` and once from the console reporter:

```
[monitoring]  Error: Import failed with 500
[monitoring] error Error: Import failed with 500 { fileName: 'projects.csv', size: 18234 }
```

With [devtools](/packages/devtools) open, the report also appears in the Errors panel with its stack and extra data. Add a reporter, as in the next section, and the same call sends it to Sentry in production.

## What is reported for you

You do not need `try`/`catch` for these:

| What | Where | How | `source` |
| --- | --- | --- | --- |
| An error thrown while a component renders | Browser | The provider wraps the app in `MonitoringErrorBoundary`, which reports, then rethrows so the router's error screen shows. | `error-boundary` |
| An uncaught error | Browser | A `window` `error` listener, unless `globalHandlers: false`. | `window` |
| A rejected promise nobody handled | Browser | A `window` `unhandledrejection` listener, unless `globalHandlers: false`. | `window` |
| An error thrown by a server route | Server | The `reportErrors` middleware, once you add it. | `server` |

Every report goes through `shouldReport` first. Expected failures are not incidents: a `KitrError` with a status below 500 (not found, validation, unauthorized) and an aborted `fetch` are dropped by default.

React retries a failed render, and StrictMode renders twice, so one render error can throw several times. The boundary reports it once.

## Reporters

A reporter sends reports to one destination. List any number in `reporters`; each report goes to all of them. A reporter that throws is ignored, so a broken one never breaks your app.

### Sentry in the browser

```sh
pnpm add @sentry/react
```

```ts
// config/monitoring.ts
import * as Sentry from '@sentry/react'
import { defineConfig, sentry } from 'kitr/monitoring'
import { env } from '#app/env'

export default defineConfig({
  reporters: [
    ...(env.VITE_SENTRY_DSN
      ? [sentry(Sentry, { dsn: env.VITE_SENTRY_DSN, release: 'acme-web@1.4.0', tracesSampleRate: 0 })]
      : []),
  ],
  tags: { app: env.VITE_APP_NAME },
})
```

In `.env`:

```sh
VITE_SENTRY_DSN=https://<key>@o123.ingest.sentry.io/456
```

You pass the Sentry module yourself, so the bundle contains `@sentry/react` in the browser and nothing kitr chose for you. Every option you pass to `sentry()` (`dsn`, `environment`, `release`, `tracesSampleRate` and any other) goes to [`Sentry.init`](https://docs.sentry.io/platforms/javascript/guides/react/configuration/options/), which the reporter calls when the monitoring service is created.

### Sentry on the server

```sh
pnpm add @sentry/node
```

```ts
// config/monitoring.ts
import * as Sentry from '@sentry/node'
import { defineConfig, sentry } from 'kitr/monitoring'

export default defineConfig({
  reporters: [...(process.env.SENTRY_DSN ? [sentry(Sentry, { dsn: process.env.SENTRY_DSN })] : [])],
  tags: { service: 'acme-api' },
})
```

In `.env`:

```sh
SENTRY_DSN=https://<key>@o123.ingest.sentry.io/789
```

See [Sentry for Node.js](https://docs.sentry.io/platforms/javascript/guides/node/). In a project with both a web and a server platform, `config/monitoring.ts` is shared, so pick the SDK per side or keep one config per platform.

The reporter maps each call to the SDK: `captureException` and `captureMessage` with your `tags`, `extra` and `level` (messages default to `info`), `setUser`, `addBreadcrumb`, `setTag` and `flush`.

### Console

```ts
// config/monitoring.ts
import { consoleReporter, defineConfig } from 'kitr/monitoring'

export default defineConfig({ reporters: [consoleReporter()], debug: false })
```

Prints exceptions with `console.error('[monitoring]', source, error, extra)` and messages with `console.info`. Breadcrumbs and users are ignored. No env variables. The provider adds it in development when `reporters` is empty. Setting `debug: false` next to it avoids printing each report twice.

### Devtools

`devtoolsReporter(hub)` sends exceptions and messages to the devtools `errors` channel and breadcrumbs to `breadcrumbs`. The provider adds it for you whenever [devtools](/packages/devtools) is active; you never list it yourself.

### Memory

`memoryReporter()` keeps reports in arrays for tests. See [Testing](#testing).

## Report a caught error

`captureException(error, context?)` reports an error you handled. The context is optional:

| Field | Description |
| --- | --- |
| `extra` | Any data that helps: ids, sizes, the input that failed. |
| `tags` | Short string values you filter by in Sentry, such as `{ feature: 'billing' }`. Merged over the config `tags`. |
| `level` | `'fatal'`, `'error'`, `'warning'`, `'info'` or `'debug'`. |
| `source` | Where it came from. The built-in sources are `error-boundary`, `window` and `server`. |

```ts
// app/features/invoices/download-invoice.ts
import type { KitrApp } from 'kitr/app'

export async function downloadInvoice(app: KitrApp, invoiceNumber: string) {
  const monitoring = app.container.use('monitoring')
  try {
    const res = await fetch(`/api/invoices/${invoiceNumber}.pdf`)
    if (!res.ok) throw new Error(`PDF download failed with ${res.status}`)
    return await res.blob()
  } catch (error) {
    monitoring.captureException(error, {
      tags: { feature: 'billing' },
      extra: { invoiceNumber },
      level: 'warning',
    })
    return null
  }
}
```

Outside React, the service is `app.container.use('monitoring')`. Don't report an error and then rethrow it to a place that reports it again, such as the error boundary or the server middleware: you get two reports for one failure. Either handle and report, or let it propagate.

## Send a message

`captureMessage(message, context?)` reports something worth knowing that is not an exception:

```ts
// app/features/projects/import-limit.ts
import type { KitrApp } from 'kitr/app'

export function warnImportLimit(app: KitrApp, teamId: string, rows: number) {
  app.container.use('monitoring').captureMessage('project import over the row limit', {
    level: 'warning',
    tags: { feature: 'import' },
    extra: { teamId, rows, limit: 5_000 },
  })
}
```

Messages skip `shouldReport`; every call is sent.

## Identify the user

`setUser(user)` attaches the signed-in user to every report that follows, so Linus can see that Ada hit the error and contact her. Call it after sign-in and pass `null` on sign-out:

```ts
// app/features/auth/session.ts
import type { KitrApp } from 'kitr/app'

export function onSignedIn(app: KitrApp, user: { id: string; email: string; teamId: string }) {
  app.container.use('monitoring').setUser({ id: user.id, email: user.email, teamId: user.teamId })
}

export function onSignedOut(app: KitrApp) {
  app.container.use('monitoring').setUser(null)
}
```

The user needs an `id`; `email`, `username` and any other field are optional. Only send what your privacy policy allows. An id alone is often enough to look the person up.

## Leave breadcrumbs

A breadcrumb is a step on the way to a possible error. Reporters that support them, such as Sentry, attach the most recent ones to the next report:

```ts
// app/features/projects/import-projects.ts
import type { KitrApp } from 'kitr/app'

export async function importProjects(app: KitrApp, file: File) {
  const monitoring = app.container.use('monitoring')
  monitoring.addBreadcrumb({ category: 'import', message: 'file selected', data: { name: file.name } })
  const text = await file.text()
  monitoring.addBreadcrumb({ category: 'import', message: 'parsed CSV', data: { rows: text.split('\n').length } })
  return text
}
```

| Field | Description |
| --- | --- |
| `message` | What happened. Required. |
| `category` | A group, such as `import`, `navigation` or `api`. |
| `level` | Same values as `level` above. |
| `data` | Extra data. |
| `timestamp` | Milliseconds since the epoch. Set to `Date.now()` when left out. |

The console and memory reporters ignore breadcrumbs; devtools lists them under Breadcrumbs.

## Tag reports

Tags are short strings you filter by. Set them in three places, from widest to narrowest:

- `tags` in `config/monitoring.ts`, on every report from the start. The provider adds `environment` with the app's mode.
- `setTag(key, value)` at run time, for something that stays true for the session, such as the team plan.
- `tags` in the context of one call, as in [Report a caught error](#report-a-caught-error).

```ts
// app/features/teams/team-context.ts
import type { KitrApp } from 'kitr/app'

export function onTeamSelected(app: KitrApp, team: { id: string; plan: 'free' | 'pro' }) {
  const monitoring = app.container.use('monitoring')
  monitoring.setTag('team', team.id)
  monitoring.setTag('plan', team.plan)
}
```

`setTag` is passed to reporters that keep their own scope, such as Sentry. The config tags and per-call tags are merged into each report by `kitr/monitoring` itself, with per-call tags winning.

## Wrap a function

`wrap(fn, context?)` runs `fn`, reports anything it throws or rejects with, and rethrows. It works for sync and async functions:

```ts
// server/services/invoice_service.ts
import type { Monitoring } from 'kitr/monitoring'

export function totalInvoice(monitoring: Monitoring, lines: Array<{ amount: number }>) {
  return monitoring.wrap(() => lines.reduce((sum, line) => sum + line.amount, 0), {
    tags: { feature: 'billing' },
  })
}

export async function sendInvoice(monitoring: Monitoring, invoiceNumber: string) {
  return monitoring.wrap(
    async () => {
      const res = await fetch(`https://billing.acme.com/invoices/${invoiceNumber}/send`, { method: 'POST' })
      if (!res.ok) throw new Error(`billing API ${res.status}`)
      return res.status
    },
    { extra: { invoiceNumber } },
  )
}
```

Use it for work that runs outside a request or render, such as a timer or a queue consumer, where nothing else would see the error.

## Ignore expected errors

`shouldReport(error, context)` decides whether `captureException` sends anything. The default is `defaultShouldReport`, which you can extend instead of replacing:

```ts
// config/monitoring.ts
import { defaultShouldReport, defineConfig } from 'kitr/monitoring'
import { env } from '#app/env'

export default defineConfig({
  reporters: [],
  shouldReport(error, context) {
    // Browser extensions throw from their own scripts; they are not our bugs.
    if (context?.source === 'window' && error instanceof Error && /extension:\/\//.test(error.stack ?? ''))
      return false
    return defaultShouldReport(error)
  },
  tags: { app: env.VITE_APP_NAME },
})
```

```ts
// scripts/should_report.ts
import { KitrError } from 'kitr/app'
import { defaultShouldReport } from 'kitr/monitoring'

defaultShouldReport(KitrError.notFound('Project')) // => false
defaultShouldReport(new KitrError('INTERNAL', 'db down')) // => true
defaultShouldReport(Object.assign(new Error('aborted'), { name: 'AbortError' })) // => false
defaultShouldReport(new Error('Import failed with 500')) // => true
```

## Show a fallback for a render error

The provider's boundary rethrows so the router's error component renders. To keep the rest of a page working when one widget fails, put your own `MonitoringErrorBoundary` around it with a `fallback`:

```tsx
// app/features/invoices/invoice-chart-section.tsx
import { MonitoringErrorBoundary } from 'kitr/monitoring/provider'
import { useService } from 'kitr/react'
import { InvoiceChart } from './invoice-chart'

export function InvoiceChartSection() {
  const monitoring = useService('monitoring')
  return (
    <MonitoringErrorBoundary
      monitoring={monitoring}
      fallback={(error, reset) => (
        <div role="alert">
          <p>The chart could not be drawn: {(error as Error).message}</p>
          <button type="button" onClick={reset}>
            Try again
          </button>
        </div>
      )}
    >
      <InvoiceChart />
    </MonitoringErrorBoundary>
  )
}
```

| Prop | Description |
| --- | --- |
| `monitoring` | The service to report to. |
| `fallback` | A node, or `(error, reset) => node`. `reset()` clears the error and renders the children again. Left out, the boundary rethrows after reporting. |
| `children` | What it guards. |

The report carries `source: 'error-boundary'` and the React component stack in `extra.componentStack`.

## Report server errors

On the server, `reportErrors(monitoring)` from `kitr/monitoring/server` is middleware that reports every error a route throws, with the method, URL and request id, then rethrows so kitr's error handler still sends the response.

In a project with React, the provider binds the service on the server too. The app boots on the first request, so resolve the service per request:

```ts
// server/main.ts
import { mountRoutes } from 'kitr/api'
import { reportErrors } from 'kitr/monitoring/server'
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'
import { routes } from '#server/routes'

export const server = createServer({ providers: rc.providers, config })
mountRoutes(server, routes)
// Report thrown errors before kitr's error handler answers.
server.use((event, next) => reportErrors(server.app.container.use('monitoring'))(event, next))
```

In a server-only project there is no provider, so create the service from the config and bind it yourself. Then `app.container.use('monitoring')` works everywhere, as `AGENTS.md` says:

```ts
// server/main.ts
import { mountRoutes } from 'kitr/api'
import { createMonitoring } from 'kitr/monitoring'
import { reportErrors } from 'kitr/monitoring/server'
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'
import { routes } from '#server/routes'

export const server = createServer({ providers: rc.providers, config })
mountRoutes(server, routes)

const monitoring = createMonitoring(config.monitoring)
server.app.container.value('monitoring', monitoring)
server.use(reportErrors(monitoring))
```

A route that throws `new Error('db down')` while handling `GET /api/projects` is reported as:

```ts
// => error: Error('db down')
// => context: {
//   source: 'server',
//   extra: { method: 'GET', url: 'https://app.acme.com/api/projects', requestId: '9b2f6c1e-...' },
//   tags: { service: 'acme-api' },
// }
```

The client still gets kitr's normal 500 response. A route that throws `KitrError.notFound()` answers 404 and is not reported. `createMonitoring` used directly does not add the console reporter or the `environment` tag; add them in the config if you want them.

## Flush before the process exits

Reporters send in the background. In a script, a serverless function or a shutdown hook, wait for them with `flush(timeoutMs?)` before the process ends:

```ts
// scripts/rebuild_invoices.ts
import { createMonitoring } from 'kitr/monitoring'
import { config } from '../config'

const monitoring = createMonitoring(config.monitoring)
try {
  throw new Error('invoice INV-2026-007 has no lines')
} catch (error) {
  monitoring.captureException(error, { tags: { job: 'rebuild_invoices' } })
} finally {
  await monitoring.flush(2_000)
}
```

`flush` waits for every reporter that has a `flush` method, up to the timeout (2 seconds by default), and never throws.

## Devtools

With [devtools](/packages/devtools) installed, the provider registers an Errors panel and a devtools reporter in development.

- The panel lists captured exceptions, messages and `setUser` calls, newest first, with the time, the `source` as a badge, the stack and the `extra` data. The latest one is expanded.
- Its tab shows a badge with the number of exceptions.
- Below the list, the last 20 breadcrumbs.
- The Clear errors action empties the list. Throw a test error throws an uncaught error, so you can check the global handler without writing code.

## Testing

`memoryReporter()` keeps every report in arrays. Boot an app with the provider and a memory reporter, run the code, and assert on what was reported:

```ts
// test/download_invoice.test.ts
import { memoryReporter } from 'kitr/monitoring'
import monitoringProvider from 'kitr/monitoring/provider'
import { createTestApp } from 'kitr/testing'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { downloadInvoice } from '#app/features/invoices/download-invoice'

afterEach(() => vi.unstubAllGlobals())

describe('downloadInvoice', () => {
  it('reports a failed download with the invoice number', async () => {
    const reporter = memoryReporter()
    const app = await createTestApp({
      providers: [monitoringProvider],
      config: { monitoring: { reporters: [reporter], globalHandlers: false } },
    })
    vi.stubGlobal('fetch', async () => new Response('nope', { status: 503 }))

    expect(await downloadInvoice(app, 'INV-2026-007')).toBeNull()

    expect(reporter.exceptions).toHaveLength(1)
    const [report] = reporter.exceptions
    expect((report?.error as Error).message).toBe('PDF download failed with 503')
    expect(report?.context).toMatchObject({
      level: 'warning',
      extra: { invoiceNumber: 'INV-2026-007' },
      tags: { environment: 'test', feature: 'billing' },
    })
  })
})
```

| Field | Holds |
| --- | --- |
| `exceptions` | `{ error, context }` for each reported exception, after `shouldReport` and with tags merged. |
| `messages` | The text of each `captureMessage`. |
| `user` | The last value passed to `setUser`. |

Breadcrumbs and tags set with `setTag` are not kept. To check that an expected error is dropped, assert `expect(reporter.exceptions).toHaveLength(0)`.

Without the provider, `createMonitoring({ reporters: [reporter] })` gives you the same service with no `environment` tag. Use it to test the server middleware without a server:

```ts
// test/report_errors.test.ts
import { createMonitoring, memoryReporter } from 'kitr/monitoring'
import { reportErrors } from 'kitr/monitoring/server'
import { expect, it } from 'vitest'

it('reports a failed route with its request id', async () => {
  const reporter = memoryReporter()
  const middleware = reportErrors(createMonitoring({ reporters: [reporter] }))
  const event = {
    req: { method: 'GET', url: 'https://app.acme.com/api/projects' },
    context: { kitr: { requestId: 'req_1' } },
  }

  await expect(
    middleware(event, async () => {
      throw new Error('db down')
    }),
  ).rejects.toThrow('db down')

  expect(reporter.exceptions[0]?.context).toEqual({
    source: 'server',
    extra: { method: 'GET', url: 'https://app.acme.com/api/projects', requestId: 'req_1' },
  })
})
```

## Extend

A reporter is an object with a `name` and a `captureException` method. Every other method is optional: `init`, `captureMessage`, `setUser`, `addBreadcrumb`, `setTag` and `flush`. See [`Reporter`](/packages/monitoring/api#reporter).

This one posts each exception to an internal endpoint, with the user and the last ten breadcrumbs:

```ts
// app/monitoring/acme-reporter.ts
import type { Breadcrumb, MonitoringUser, Reporter } from 'kitr/monitoring'

export function acmeReporter(options: { endpoint: string }): Reporter {
  let user: MonitoringUser | null = null
  const crumbs: Breadcrumb[] = []
  const pending = new Set<Promise<unknown>>()

  return {
    name: 'acme',
    setUser: (next) => {
      user = next
    },
    addBreadcrumb: (crumb) => {
      crumbs.push(crumb)
      if (crumbs.length > 10) crumbs.shift()
    },
    captureException(error, context) {
      const body = JSON.stringify({
        message: error instanceof Error ? error.message : String(error),
        stack: error instanceof Error ? error.stack : undefined,
        user,
        breadcrumbs: crumbs,
        ...context,
      })
      const sent = fetch(options.endpoint, { method: 'POST', body, keepalive: true })
      pending.add(sent)
      void sent.finally(() => pending.delete(sent))
    },
    async flush(timeoutMs = 2_000) {
      const timeout = new Promise<false>((resolve) => setTimeout(() => resolve(false), timeoutMs))
      return Promise.race([Promise.all(pending).then(() => true), timeout])
    },
  }
}
```

Register it in `config/monitoring.ts` next to any others:

```ts
// config/monitoring.ts
import { defineConfig } from 'kitr/monitoring'
import { acmeReporter } from '#app/monitoring/acme-reporter'
import { env } from '#app/env'

export default defineConfig({
  reporters: [acmeReporter({ endpoint: 'https://errors.acme.com/ingest' })],
  tags: { app: env.VITE_APP_NAME },
})
```

`captureException` must not throw or block: return at once and send in the background. The service calls each reporter inside `try`/`catch` and ignores rejected promises, so a failing endpoint loses its reports silently. `init` runs once, when the service is created. Breadcrumbs reach you without the merged tags; exceptions and messages arrive with them.

## Next steps

- [Monitoring API reference](/packages/monitoring/api): every export with its signature.
- [Sentry for JavaScript](https://docs.sentry.io/platforms/javascript/): the SDK behind the `sentry()` reporter.
- [Logger](/packages/logger): lines for debugging, next to reports for fixing.
- [Server](/packages/server): request ids and kitr's error responses.
- [Devtools](/packages/devtools): the Errors panel in development.
- [Auth](/packages/auth): where to call `setUser` after sign-in.


# Native API

Source: https://kitr.dev/packages/native/api

Every export of `kitr/native`, `kitr/native/react`, `kitr/native/provider`, read from the published type definitions. The [guide](/packages/native) shows them in use.

## kitr/native

### createMemoryNativeDrivers

```ts
function createMemoryNativeDrivers(overrides?: NativeConfig['drivers']): {
  clipboard: ClipboardDriver;
  share: ShareDriver;
  haptics: HapticsDriver;
  geolocation: GeolocationDriver;
  camera: CameraDriver;
  biometrics: BiometricsDriver;
  shared: SharePayload[];
  haptics_log: HapticKind[];
};
```

In-memory drivers for all six capabilities, for tests and the server. `shared` and `haptics_log`
record what was shared and played; pass overrides to replace any driver.

### createNative

```ts
function createNative(config?: NativeConfig, app?: KitrApp): Native;
```

Build the `native` service. Per capability it uses `config.drivers`, else the driver a platform
registered on `app`, else the web driver, else an unsupported stand-in.

### useNative

```ts
function useNative(app: KitrApp): Native;
```

The app's `native` service, outside React. Same as `app.container.use('native')`.

### webBiometrics

```ts
function webBiometrics(options?: {
  storageKey?: string;
}): BiometricsDriver | null;
```

WebAuthn user verification with a platform authenticator (Touch ID, Windows Hello, Android
screen lock). The first call registers a device-only credential for this site (that prompt is
itself the check); later calls ask for that credential by id, so people without a passkey get
the fingerprint or PIN prompt rather than an empty passkey picker. A local presence check, like
the native ones: to prove identity to your server, verify a WebAuthn assertion there.

### webCamera

```ts
function webCamera(): CameraDriver | null;
```

Camera driver that opens a hidden image file input, with `capture` for the camera source.
Resolves null when cancelled; null itself only where there is no `document`.

### webClipboard

```ts
function webClipboard(): ClipboardDriver | null;
```

Clipboard driver on the Clipboard API. Null where `navigator.clipboard` is missing (no HTTPS, no browser).

### webGeolocation

```ts
function webGeolocation(): GeolocationDriver | null;
```

Geolocation driver on the browser Geolocation API. Null where `navigator.geolocation` is missing.

### webHaptics

```ts
function webHaptics(): HapticsDriver | null;
```

Haptics driver that maps each kind to a `navigator.vibrate` pattern. Null where vibration is missing.

### webShare

```ts
function webShare(): ShareDriver | null;
```

Share driver on Web Share. Resolves false when dismissed; null where `navigator.share` is missing.

### UnsupportedError

```ts
class UnsupportedError extends Error {
  capability: NativeCapability;
  constructor(capability: NativeCapability);
}
```

Thrown when a method is called on a capability that has no driver here. `capability` names it.

### defineConfig

```ts
const defineConfig: <const C extends NativeConfig>(config: C) => C;
```

Types `config/native.ts`. Returns the object unchanged.

### BiometricsDriver

```ts
interface BiometricsDriver {
  /** Whether the device has an enrolled biometric or device credential. */
  available(): Promise<boolean>;
  /** Prompt; resolves to true on success, false when cancelled or failed. */
  authenticate(options?: {
    reason?: string;
  }): Promise<boolean>;
}
```

Asks for a fingerprint, face or device PIN to confirm someone is at the device.

### CameraDriver

```ts
interface CameraDriver {
  /** Take a photo (or, on the web, open the capture-enabled file input). */
  capture(options?: {
    source?: 'camera' | 'library';
    quality?: number;
  }): Promise<Photo | null>;
}
```

Takes or picks a photo.

### Capability

```ts
interface Capability<T> {
  /** True when a driver exists for this capability here. */
  supported: boolean;
  /** The active driver (a stand-in that rejects with `UnsupportedError` when unsupported). */
  driver: T;
  /** Where the driver came from: `configured`, the registering platform, `native`, `web` or `unsupported`. */
  name: string;
}
```

What every capability on the `native` service carries next to its driver's methods.

### ClipboardDriver

```ts
/** Reads and writes plain text on the system clipboard. */
interface ClipboardDriver {
  /** Resolves to the clipboard's text. Browsers ask permission first and reject when refused. */
  readText(): Promise<string>;
  /** Puts `text` on the clipboard. On the web, call it from a click or key press. */
  writeText(text: string): Promise<void>;
}
```

Reads and writes plain text on the system clipboard.

### GeolocationDriver

```ts
interface GeolocationDriver {
  /** Resolve the current position. `highAccuracy` asks for GPS; `timeout` is in milliseconds. */
  current(options?: {
    highAccuracy?: boolean;
    timeout?: number;
  }): Promise<Position>;
  /** Call `listener` with each new position until the returned function is called. */
  watch(listener: (position: Position) => void, options?: {
    highAccuracy?: boolean;
  }): () => void;
}
```

Reads the device's location once or continuously.

### HapticsDriver

```ts
interface HapticsDriver {
  /** Play the feedback for `kind`. */
  impact(kind: HapticKind): Promise<void>;
}
```

Plays haptic feedback (a vibration pattern on the web).

### Native

```ts
interface Native {
  /** Read and write the clipboard. */
  clipboard: Capability<ClipboardDriver> & ClipboardDriver;
  /** Open the share sheet. */
  share: Capability<ShareDriver> & ShareDriver;
  /** Play haptic feedback. */
  haptics: Capability<HapticsDriver> & HapticsDriver;
  /** Read or follow the device's location. */
  geolocation: Capability<GeolocationDriver> & GeolocationDriver;
  /** Take or pick a photo. */
  camera: Capability<CameraDriver> & CameraDriver;
  /** Confirm presence with a fingerprint, face or device PIN. */
  biometrics: Capability<BiometricsDriver> & BiometricsDriver;
  /** Which capabilities have a working driver, for devtools and feature gating. */
  supported(): Record<NativeCapability, boolean>;
}
```

The `native` service: six device capabilities, each with its methods and its `supported` flag.

### NativeConfig

```ts
interface NativeConfig {
  /** Replace individual drivers (tests, custom hardware). */
  drivers?: Partial<{
    clipboard: ClipboardDriver;
    share: ShareDriver;
    haptics: HapticsDriver;
    geolocation: GeolocationDriver;
    camera: CameraDriver;
    biometrics: BiometricsDriver;
  }>;
}
```

Options for `config/native.ts` and `createNative()`.

### Photo

```ts
interface Photo {
  /** The image data (a `File` on the web). */
  blob: Blob;
  /** Its MIME type, such as `image/jpeg`. */
  type: string;
  /** Where the image came from. */
  source: 'camera' | 'library';
}
```

A photo taken with the camera or picked from the library.

### Position

```ts
interface Position {
  /** Degrees north of the equator. */
  latitude: number;
  /** Degrees east of Greenwich. */
  longitude: number;
  /** Radius of uncertainty, in metres. */
  accuracy: number;
  /** Metres above sea level, or null when unknown. */
  altitude?: number | null;
  /** Direction of travel in degrees from north, or null when unknown. */
  heading?: number | null;
  /** Metres per second, or null when unknown. */
  speed?: number | null;
  /** When the fix was taken, in milliseconds since the epoch. */
  timestamp: number;
}
```

A location fix, in the shape of the browser's `GeolocationCoordinates` plus its time.

### ShareDriver

```ts
interface ShareDriver {
  /** Whether this payload can be shared here, so a share button can hide itself. */
  canShare(payload: SharePayload): boolean;
  /** Resolves to true when shared, false when dismissed. */
  share(payload: SharePayload): Promise<boolean>;
}
```

Opens the system share sheet.

### SharePayload

```ts
interface SharePayload {
  /** Title shown by targets that have one, such as an email subject. */
  title?: string;
  /** Body text. */
  text?: string;
  /** A link to share. */
  url?: string;
  /** Files to share. Check `canShare({ files })` first: not every device shares files. */
  files?: File[];
}
```

What to hand to the share sheet. Every field is optional; most targets use `url` or `text`.

### HapticKind

```ts
type HapticKind = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';
```

The feel of a haptic: three impact strengths, three outcomes and a selection tick.

### NativeCapability

```ts
type NativeCapability = 'clipboard' | 'share' | 'haptics' | 'geolocation' | 'camera' | 'biometrics';
```

The name of one of the six capabilities, as used in `supported()` and `app.drivers.register()`.

## kitr/native/react

### useClipboard

```ts
function useClipboard(timeout?: number): {
  copy: (text: string) => Promise<void>;
  copied: boolean;
  supported: boolean;
};
```

`const { copy, copied } = useClipboard()`: copy text and show a confirmation for `timeout` ms.

### useGeolocation

```ts
function useGeolocation(options?: {
  watch?: boolean;
  highAccuracy?: boolean;
}): {
  position: Position | null;
  error: Error | null;
  supported: boolean;
};
```

`{ position, error, supported }`: the current position, read on mount and updated while mounted
when `watch` is true. `error` holds a failure of the first read.

### useNative

```ts
function useNative(): Native;
```

The app's `native` service in a component.

### useShare

```ts
function useShare(): {
  supported: boolean;
  canShare: (payload: SharePayload) => boolean;
  share: (payload: SharePayload) => Promise<boolean>;
};
```

`const { share, canShare } = useShare()`: the share sheet, with a flag to hide the button where there is none.

## kitr/native/provider

### nativeProvider

```ts
const nativeProvider: import("@kitr/core").KitrProvider;
```

Binds `native` from the drivers platform packages registered (`clipboard`, `share`, `haptics`,
`geolocation`, `camera`, `biometrics`) with web drivers for the rest.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Native

Source: https://kitr.dev/packages/native

Copy a link, open the share sheet, buzz the phone when an order goes through, read where someone is standing, take a photo, ask for a fingerprint: every app reaches for these sooner or later, and every platform has its own API for each one. `kitr/native` puts the six behind one `native` service. Each capability has a web driver built on the matching browser API, reports whether it works on this device, and can be replaced by a native driver without changing the code that calls it.

The web drivers use the [Clipboard API](https://developer.mozilla.org/docs/Web/API/Clipboard_API), [Web Share](https://developer.mozilla.org/docs/Web/API/Web_Share_API), [`navigator.vibrate`](https://developer.mozilla.org/docs/Web/API/Navigator/vibrate), the [Geolocation API](https://developer.mozilla.org/docs/Web/API/Geolocation_API), a file input with `capture`, and [WebAuthn](https://developer.mozilla.org/docs/Web/API/Web_Authentication_API) with the device's own authenticator. kitr adds the `supported` flag, a typed `UnsupportedError`, React hooks, memory drivers for tests and a driver slot per capability.

It runs in the browser and in desktop and mobile shells. It does not sign people in: for that use [Auth](/packages/auth), and for files people open and save use [Files](/packages/files).

This guide follows Acme's order screen at `app.acme.com`: Ada copies an invoice link, shares it with Grace, photographs a delivery note and unlocks the invoices page with her fingerprint.

## Install

```sh
kitr add native
```

What `kitr add` does:

- Adds [Platform](/packages/platform) first when the project does not have it yet, because `native` requires `platform`. The `desktop` and `mobile` kits already include it.
- Installs `@kitr/native`.
- Adds `() => import('@kitr/native/provider')` to `providers` in `kitrrc.ts`.
- Adds `@kitr/native` to `packages` in `kitrrc.ts`.
- Adds a `## kitr: native` section to `AGENTS.md`: the six capabilities come from `useNative()`, `useClipboard()`, `useShare()` and `useGeolocation()` in `kitr/native/react`, check `.supported` (or `canShare`) before showing a button, and an unsupported capability rejects with `UnsupportedError`.

It writes no config file and adds no environment variables or scripts. `kitr add native` asks no questions, and no kit includes it. It is a client package, so a server-only project skips it with a warning. To preview the changes:

```sh
kitr add native --dry-run
```

`kitr remove native` removes the provider, the `packages` entry, the dependency and the `AGENTS.md` section, and deletes `config/native.ts` if you created one. It then lists the files that still import `kitr/native`.

## Configure

`kitr/native` has no config file. The provider picks a driver per capability on its own: a driver you configure, else one a platform package registered, else the web driver. To replace drivers for the whole app, create `config/native.ts` yourself. The app loads every file in `config/` under its file name:

```ts
// config/native.ts
import { defineConfig } from 'kitr/native'
import { electronClipboard } from '#app/native/electron-clipboard'

export default defineConfig({
  drivers: {
    clipboard: electronClipboard(),
  },
})
```

| Option | Default | Description |
| --- | --- | --- |
| `drivers` | `{}` | Drivers that win over registered and web drivers, one key per capability. |
| `drivers.clipboard` | registered, else `webClipboard()` | A `ClipboardDriver`: `readText()` and `writeText(text)`. |
| `drivers.share` | registered, else `webShare()` | A `ShareDriver`: `canShare(payload)` and `share(payload)`. |
| `drivers.haptics` | registered, else `webHaptics()` | A `HapticsDriver`: `impact(kind)`. |
| `drivers.geolocation` | registered, else `webGeolocation()` | A `GeolocationDriver`: `current(options)` and `watch(listener, options)`. |
| `drivers.camera` | registered, else `webCamera()` | A `CameraDriver`: `capture(options)`. |
| `drivers.biometrics` | registered, else `webBiometrics()` | A `BiometricsDriver`: `available()` and `authenticate(options)`. |

The same object goes to `createNative(config, app)` when you build the service by hand, as in tests. Writing a driver is covered under [Extend](#extend).

## Copy your first link

`useClipboard()` copies text and flips `copied` to `true` for 1.5 seconds, long enough for a "Copied" label:

```tsx
// app/features/invoices/copy-invoice-link.tsx
import { useClipboard } from 'kitr/native/react'

export function CopyInvoiceLink({ invoiceId }: { invoiceId: string }) {
  const { copy, copied, supported } = useClipboard()
  if (!supported) return null
  const url = `https://app.acme.com/invoices/${invoiceId}`
  return (
    <button type="button" onClick={() => copy(url)}>
      {copied ? 'Copied' : 'Copy link'}
    </button>
  )
}
```

Render it on the invoice page:

```tsx
// app/routes/invoices/$invoiceId.tsx
import { createFileRoute } from 'kitr/router'
import { CopyInvoiceLink } from '#app/features/invoices/copy-invoice-link'

export const Route = createFileRoute('/invoices/$invoiceId')({
  component: InvoicePage,
})

function InvoicePage() {
  const { invoiceId } = Route.useParams()
  return (
    <main>
      <h1>Invoice {invoiceId}</h1>
      <CopyInvoiceLink invoiceId={invoiceId} />
    </main>
  )
}
```

Ada clicks **Copy link**, the label reads **Copied**, and `https://app.acme.com/invoices/inv_1042` is on her clipboard. Pass another duration as the first argument: `useClipboard(3000)`. The button hides itself where the page has no Clipboard API, which is the case on plain `http://` pages other than `localhost`.

## Check what the device supports

Every capability carries three fields next to its methods:

| Field | Description |
| --- | --- |
| `supported` | `true` when a driver exists for this capability. |
| `name` | Where the driver came from: `'configured'`, the registering platform (such as `'mobile'`), `'native'` when the platform gave no name, `'web'`, or `'unsupported'`. |
| `driver` | The driver object itself. |

`native.supported()` reports all six at once. In a component, read the service with `useNative()`:

```tsx
// app/features/orders/device-features.tsx
import { useNative } from 'kitr/native/react'

export function DeviceFeatures() {
  const native = useNative()
  const features = native.supported()
  // => { clipboard: true, share: false, haptics: false, geolocation: true, camera: true, biometrics: true }
  return (
    <ul>
      {Object.entries(features).map(([name, on]) => (
        <li key={name}>
          {name}: {on ? native[name as keyof typeof features].name : 'not on this device'}
        </li>
      ))}
    </ul>
  )
}
```

The example result is desktop Chrome: no Web Share on Linux, no vibration. When the [Devtools](/packages/devtools) provider is installed, the service logs the same object under `native` as it starts.

The web camera driver always exists in a browser, because it only opens a file input. On a laptop with no camera that input opens the file picker instead.

## Copy and paste text

Outside the hook, `native.clipboard` has `writeText(text)` and `readText()`:

```tsx
// app/features/orders/paste-order-number.tsx
import { useNative } from 'kitr/native/react'
import { useState } from 'react'

export function PasteOrderNumber({ onFound }: { onFound: (orderId: string) => void }) {
  const { clipboard } = useNative()
  const [error, setError] = useState<string | null>(null)
  if (!clipboard.supported) return null
  async function paste() {
    try {
      const text = await clipboard.readText()
      const match = text.match(/ord_\d+/)
      if (match) onFound(match[0])
      else setError('No order number on the clipboard')
    } catch {
      setError('Allow clipboard access to paste')
    }
  }
  return (
    <>
      <button type="button" onClick={paste}>Paste order number</button>
      {error && <p role="alert">{error}</p>}
    </>
  )
}
```

Browsers ask permission before a page reads the clipboard, and reject with the browser's own `NotAllowedError` when the person says no. Writing needs no prompt but must happen during a click or key press. Call `writeText` from the handler, not from an effect.

## Open the share sheet

`useShare()` returns `{ supported, canShare, share }`. Show a share button where the device has a share sheet and fall back to copying everywhere else:

```tsx
// app/features/invoices/share-invoice.tsx
import { useClipboard, useShare } from 'kitr/native/react'

export function ShareInvoice({ invoiceId, total }: { invoiceId: string; total: string }) {
  const { canShare, share } = useShare()
  const { copy, copied } = useClipboard()
  const payload = {
    title: `Acme invoice ${invoiceId}`,
    text: `Invoice ${invoiceId} for ${total}`,
    url: `https://app.acme.com/invoices/${invoiceId}`,
  }
  if (canShare(payload))
    return (
      <button type="button" onClick={() => share(payload)}>
        Share
      </button>
    )
  return (
    <button type="button" onClick={() => copy(payload.url)}>
      {copied ? 'Copied' : 'Copy link'}
    </button>
  )
}
```

`share()` resolves to `true` when Ada picked a target and `false` when she closed the sheet. Any other failure rejects with the browser's error, for example `NotAllowedError` when `share()` was not called from a click. `canShare` from the hook is `false` when the capability is unsupported, so it is safe to call everywhere.

To act on the result:

```tsx
// app/features/invoices/use-share-invoice.ts
import { useShare } from 'kitr/native/react'

export function useShareInvoice() {
  const { share } = useShare()
  return async (invoiceId: string) => {
    const shared = await share({ url: `https://app.acme.com/invoices/${invoiceId}` })
    // => true when sent, false when Ada closed the sheet
    return shared ? 'Invoice shared' : null
  }
}
```

## Share a file

The payload takes `files: File[]` as well. Browsers that cannot share files say so through `canShare`, so check with the files included:

```tsx
// app/features/invoices/share-invoice-pdf.tsx
import { useShare } from 'kitr/native/react'

export function ShareInvoicePdf({ invoiceId }: { invoiceId: string }) {
  const { canShare, share } = useShare()
  async function sharePdf() {
    const response = await fetch(`/api/invoices/${invoiceId}/pdf`)
    const file = new File([await response.blob()], `acme-${invoiceId}.pdf`, {
      type: 'application/pdf',
    })
    if (!canShare({ files: [file] })) {
      window.open(`/api/invoices/${invoiceId}/pdf`)
      return
    }
    await share({ title: `Invoice ${invoiceId}`, files: [file] })
  }
  return (
    <button type="button" onClick={sharePdf}>
      Send PDF
    </button>
  )
}
```

Where the browser has `navigator.share` but no `navigator.canShare`, the web driver answers `false` for any payload with files and `true` otherwise.

## Give haptic feedback

`haptics.impact(kind)` plays a short vibration. Use it to confirm something the person did, such as placing an order:

```tsx
// app/features/orders/place-order-button.tsx
import { useNative } from 'kitr/native/react'

export function PlaceOrderButton({ onPlace }: { onPlace: () => Promise<void> }) {
  const { haptics } = useNative()
  async function place() {
    try {
      await onPlace()
      if (haptics.supported) await haptics.impact('success')
    } catch {
      if (haptics.supported) await haptics.impact('error')
    }
  }
  return (
    <button type="button" onClick={place}>
      Place order
    </button>
  )
}
```

The web driver maps each kind to a [vibration pattern](https://developer.mozilla.org/docs/Web/API/Vibration_API) in milliseconds. Only some Android browsers vibrate; Safari and desktop browsers have no `navigator.vibrate`, so `supported` is `false` there.

| Kind | Web pattern (ms) | Use it for |
| --- | --- | --- |
| `selection` | `5` | Moving through a picker or toggling a switch |
| `light` | `10` | A small tap, such as adding a line to an order |
| `medium` | `20` | A firmer tap |
| `heavy` | `40` | A strong tap |
| `success` | `[15, 40, 15]` | An order placed, a payment taken |
| `warning` | `[30, 60, 30]` | Something needs a look |
| `error` | `[50, 50, 50, 50, 50]` | A failed action |

Don't call `impact` without checking `supported` first: on an unsupported device it rejects with `UnsupportedError`, and a haptic is never worth an error message.

## Read the current location

`geolocation.current()` resolves to a `Position` once. Acme's drivers check in at a delivery address:

```tsx
// app/features/orders/check-in-button.tsx
import { useNative } from 'kitr/native/react'

export function CheckInButton({ orderId }: { orderId: string }) {
  const { geolocation } = useNative()
  if (!geolocation.supported) return null
  async function checkIn() {
    try {
      const position = await geolocation.current({ highAccuracy: true, timeout: 10_000 })
      // => { latitude: 51.5072, longitude: -0.1276, accuracy: 12, altitude: null, heading: null, speed: null, timestamp: 1767225600000 }
      await fetch(`/api/orders/${orderId}/check-in`, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ latitude: position.latitude, longitude: position.longitude }),
      })
    } catch (error) {
      // GeolocationPositionError: code 1 denied, 2 unavailable, 3 timed out
      console.warn('No location', error)
    }
  }
  return (
    <button type="button" onClick={checkIn}>
      Check in at delivery
    </button>
  )
}
```

| Option | Default | Description |
| --- | --- | --- |
| `highAccuracy` | `false` | Ask for GPS-level accuracy. Slower and uses more battery. |
| `timeout` | none | Give up after this many milliseconds. |

On the web the call rejects with the browser's [`GeolocationPositionError`](https://developer.mozilla.org/docs/Web/API/GeolocationPositionError): `code` 1 when Ada denies the prompt, 2 when no position is available and 3 on timeout. `accuracy` is in metres; `altitude`, `heading` and `speed` are `null` when the device does not know them.

## Follow the location

`useGeolocation()` reads the position once on mount. With `watch: true` it keeps `position` fresh until the component unmounts:

```tsx
// app/features/orders/delivery-tracker.tsx
import { useGeolocation } from 'kitr/native/react'

export function DeliveryTracker() {
  const { position, error, supported } = useGeolocation({ watch: true, highAccuracy: true })
  if (!supported) return <p>Location is not available on this device.</p>
  if (error) return <p role="alert">Location blocked: {error.message}</p>
  if (!position) return <p>Finding you…</p>
  return (
    <p>
      {position.latitude.toFixed(4)}, {position.longitude.toFixed(4)} (±{Math.round(position.accuracy)} m)
    </p>
  )
}
```

`error` holds a failure of the first read only. The web driver's watch has no error callback, so a permission revoked while watching stops updates without setting `error`.

Outside React, `watch` returns a function that stops it:

```ts
// app/features/orders/track-delivery.ts
import type { Native } from 'kitr/native'

export function trackDelivery(native: Native, report: (lat: number, lng: number) => void) {
  const stop = native.geolocation.watch((p) => report(p.latitude, p.longitude), {
    highAccuracy: true,
  })
  return stop
}
```

On an unsupported device `watch` returns a no-op stop function instead of throwing.

## Take a photo

`camera.capture()` resolves to a `Photo` (`{ blob, type, source }`) or `null` when the person cancels. Grace photographs a signed delivery note and attaches it to the order:

```tsx
// app/features/orders/attach-delivery-note.tsx
import { useNative } from 'kitr/native/react'

export function AttachDeliveryNote({ orderId }: { orderId: string }) {
  const { camera } = useNative()
  async function attach(source: 'camera' | 'library') {
    const photo = await camera.capture({ source })
    if (!photo) return
    // => { blob: File, type: 'image/jpeg', source: 'camera' }
    const body = new FormData()
    body.append('note', photo.blob, `delivery-${orderId}.jpg`)
    await fetch(`/api/orders/${orderId}/delivery-note`, { method: 'POST', body })
  }
  return (
    <>
      <button type="button" onClick={() => attach('camera')}>Take photo</button>
      <button type="button" onClick={() => attach('library')}>Choose photo</button>
    </>
  )
}
```

| Option | Default | Description |
| --- | --- | --- |
| `source` | `'camera'` | `'camera'` opens the camera; `'library'` opens the photo library or file picker. |
| `quality` | none | A hint for native drivers. The web driver ignores it and returns the file as picked. |

On the web, `capture()` opens a hidden `<input type="file" accept="image/*">`. With `source: 'camera'` it adds `capture="environment"`, which opens the rear camera on phones; desktop browsers show the file picker either way. Call it from a click, or the browser refuses to open the input. To send the photo to your server, [Uploads](/packages/uploads) takes the `blob` as is.

## Unlock with biometrics

`biometrics.available()` says whether the device has Touch ID, Face ID, Windows Hello or a screen lock set up. `authenticate()` shows the prompt and resolves to `true` on success and `false` when the person cancels or fails:

```tsx
// app/features/invoices/invoice-lock.tsx
import { useNative } from 'kitr/native/react'
import { type ReactNode, useEffect, useState } from 'react'

export function InvoiceLock({ children }: { children: ReactNode }) {
  const { biometrics, haptics } = useNative()
  const [available, setAvailable] = useState<boolean | null>(null)
  const [unlocked, setUnlocked] = useState(false)
  useEffect(() => {
    biometrics.available().then(setAvailable)
  }, [biometrics])
  if (available === null) return null
  if (!available || unlocked) return <>{children}</>
  async function unlock() {
    const ok = await biometrics.authenticate({ reason: 'Open Acme invoices' })
    if (ok) {
      setUnlocked(true)
      if (haptics.supported) await haptics.impact('success')
    }
  }
  return (
    <button type="button" onClick={unlock}>
      Unlock invoices
    </button>
  )
}
```

`available()` resolves to `false` on an unsupported device rather than throwing, so you can call it without checking `supported`.

On the web the driver uses WebAuthn with the platform authenticator. The first `authenticate()` registers a credential for this site on this device, and that prompt is itself the check. It saves the credential id in `localStorage` under `kitr:biometrics:credential`; later calls ask for that credential, so the person sees the fingerprint or PIN prompt instead of a passkey picker. If the device no longer has the credential, the driver forgets the id and the next call registers a new one. A cancel keeps the id. The web driver does not show `reason`; native drivers pass it to the system prompt.

> **Warning**
> `authenticate()` proves someone is at the device. It does not prove who they are to your server, and a script on the page can skip the check. Never unlock data on the server because the client said `true`. For sign-in, verify a passkey assertion on the server with [Auth](/packages/auth).

To keep the credential id under another key, for example one per signed-in user, configure the web driver yourself:

```ts
// config/native.ts
import { defineConfig, webBiometrics } from 'kitr/native'

export default defineConfig({
  drivers: {
    biometrics: webBiometrics({ storageKey: 'acme:biometrics:credential' }) ?? undefined,
  },
})
```

`webBiometrics()` returns `null` where the browser has no WebAuthn, which `?? undefined` turns into "use the default".

## Handle unsupported capabilities

A capability with no driver still exists on the service, with `supported: false` and `name: 'unsupported'`. Most methods reject with `UnsupportedError`; three answer safely instead so that feature checks never throw:

| Call | Unsupported result |
| --- | --- |
| `share.canShare(payload)` | `false` |
| `biometrics.available()` | `false` |
| `geolocation.watch(listener)` | A stop function that does nothing |
| Every other method | Rejects with `UnsupportedError` |

Catch it by class and read `capability`:

```ts
// app/features/invoices/copy-or-explain.ts
import { type Native, UnsupportedError } from 'kitr/native'

export async function copyInvoiceNumber(native: Native, invoiceId: string) {
  try {
    await native.clipboard.writeText(invoiceId)
    return 'Copied'
  } catch (error) {
    if (error instanceof UnsupportedError) return `Copy ${invoiceId} by hand`
    // error.capability => 'clipboard'
    // error.message => 'kitr/native: clipboard is not supported on this platform'
    throw error
  }
}
```

Checking `supported` before rendering the button is the better habit. Catching `UnsupportedError` is for code paths where you cannot hide the control.

## Use it outside React

Outside components, read the service from the app's container. `useNative(app)` from `kitr/native` does the same thing:

```ts
// app/features/orders/after-place.ts
import type { KitrApp } from 'kitr/app'
import { useNative } from 'kitr/native'

export async function afterOrderPlaced(app: KitrApp, orderId: string) {
  const native = useNative(app) // same as app.container.use('native')
  if (native.haptics.supported) await native.haptics.impact('success')
  if (native.clipboard.supported) await native.clipboard.writeText(orderId)
}
```

Methods are bound to their driver, so `const { writeText } = native.clipboard` works too. To build a service with no app at all, call `createNative(config)`; with no `config.drivers` and no app it uses the web drivers.

## Where each capability comes from

For each capability the service takes the first of these that exists:

1. The driver in `config.drivers`, named `'configured'`.
2. A driver a provider registered with `app.drivers.register('<capability>', driver, { platform })`, named after `platform`.
3. The web driver, named `'web'`.
4. Nothing: `supported: false`, named `'unsupported'`.

| Capability | Web driver | Works in |
| --- | --- | --- |
| `clipboard` | `webClipboard()`, Clipboard API | Every current browser, on HTTPS or `localhost` |
| `share` | `webShare()`, Web Share | Safari, Chrome on Android, ChromeOS and Windows, Edge |
| `haptics` | `webHaptics()`, `navigator.vibrate` | Chrome and Firefox on Android |
| `geolocation` | `webGeolocation()`, Geolocation API | Every current browser, on HTTPS |
| `camera` | `webCamera()`, file input with `capture` | Every browser |
| `biometrics` | `webBiometrics()`, WebAuthn platform authenticator | Browsers with WebAuthn, on HTTPS |

Desktop and mobile shells run the app in a webview, so the web drivers apply there too. Today [Desktop](/packages/desktop) and [Mobile](/packages/mobile) register only `platform` and `storage` drivers, none of these six. To use the native clipboard, Face ID or real haptics in a shell, register a driver as shown under [Extend](#extend).

## Errors

| Error | When | What to do |
| --- | --- | --- |
| `UnsupportedError` (`capability` set) | A method other than `canShare`, `available` or `watch` on a capability with no driver. | Check `supported` before showing the control. |
| `NotAllowedError` (browser) | Clipboard read denied, or `share()` / `writeText()` not called from a click. | Call from an event handler; explain the permission. |
| `GeolocationPositionError` (browser) | `current()` denied (code 1), unavailable (2) or timed out (3). | Show a message, and offer a manual address. |

`share()` resolving to `false` and `authenticate()` or `capture()` resolving to `false` / `null` are cancels, not errors.

## Testing

`createMemoryNativeDrivers()` returns six drivers that work in Node and in a DOM test, plus two logs: `shared` (every payload passed to `share`) and `haptics_log` (every kind passed to `impact`). Its defaults:

| Capability | Memory behaviour |
| --- | --- |
| `clipboard` | Keeps the last written text in memory. |
| `share` | `canShare` is `true`; `share` records the payload and resolves `true`. |
| `haptics` | Records the kind. |
| `geolocation` | `current()` resolves `{ latitude: 0, longitude: 0, accuracy: 1, timestamp: Date.now() }`; `watch` never calls back. |
| `camera` | `capture()` resolves `null`. |
| `biometrics` | `available()` and `authenticate()` resolve `true`. |

Pass overrides to replace one, and hand the result to the app through `config.native.drivers`:

```tsx
// app/features/invoices/share-invoice.test.tsx
import { fireEvent, screen, waitFor } from '@testing-library/react'
import { createMemoryNativeDrivers } from 'kitr/native'
import { nativeProvider } from 'kitr/native/provider'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { describe, expect, it } from 'vitest'
import { InvoiceLock } from './invoice-lock'
import { ShareInvoice } from './share-invoice'

describe('invoice sharing', () => {
  it('shares the invoice link and records it', async () => {
    const drivers = createMemoryNativeDrivers()
    const app = await createTestApp({
      providers: [nativeProvider],
      config: { native: { drivers } },
    })
    renderWithKitr(<ShareInvoice invoiceId="inv_1042" total="$1,280.00" />, { app })
    fireEvent.click(screen.getByRole('button', { name: 'Share' }))
    await waitFor(() => expect(drivers.shared).toHaveLength(1))
    expect(drivers.shared[0]).toEqual({
      title: 'Acme invoice inv_1042',
      text: 'Invoice inv_1042 for $1,280.00',
      url: 'https://app.acme.com/invoices/inv_1042',
    })
  })

  it('falls back to copying when there is no share sheet', async () => {
    const drivers = createMemoryNativeDrivers({
      share: { canShare: () => false, share: async () => false },
    })
    const app = await createTestApp({
      providers: [nativeProvider],
      config: { native: { drivers } },
    })
    renderWithKitr(<ShareInvoice invoiceId="inv_1042" total="$1,280.00" />, { app })
    fireEvent.click(screen.getByRole('button', { name: 'Copy link' }))
    await screen.findByRole('button', { name: 'Copied' })
    const native = app.container.use('native')
    expect(await native.clipboard.readText()).toBe('https://app.acme.com/invoices/inv_1042')
  })

  it('unlocks invoices with a fingerprint and buzzes', async () => {
    const drivers = createMemoryNativeDrivers()
    const app = await createTestApp({
      providers: [nativeProvider],
      config: { native: { drivers } },
    })
    renderWithKitr(
      <InvoiceLock>
        <p>Invoice list</p>
      </InvoiceLock>,
      { app },
    )
    fireEvent.click(await screen.findByRole('button', { name: 'Unlock invoices' }))
    await screen.findByText('Invoice list')
    expect(drivers.haptics_log).toEqual(['success'])
  })
})
```

To test a fallback, leave a capability out on purpose. `createNative()` with no drivers in Node reports every capability unsupported:

```ts
// app/features/invoices/copy-or-explain.test.ts
import { createNative } from 'kitr/native'
import { expect, it } from 'vitest'
import { copyInvoiceNumber } from './copy-or-explain'

it('asks for a manual copy when there is no clipboard', async () => {
  const native = createNative()
  expect(native.clipboard.supported).toBe(false)
  expect(await copyInvoiceNumber(native, 'inv_1042')).toBe('Copy inv_1042 by hand')
})
```

A location fix for a test is one override: `createMemoryNativeDrivers({ geolocation: { current: async () => ({ latitude: 51.5, longitude: -0.12, accuracy: 5, timestamp: 0 }), watch: () => () => {} } })`.

## Extend

Each capability has its own driver interface. A driver is a plain object (or a class instance: methods run with the driver as `this`):

```ts
interface ClipboardDriver {
  readText(): Promise<string>
  writeText(text: string): Promise<void>
}
interface ShareDriver {
  canShare(payload: SharePayload): boolean
  share(payload: SharePayload): Promise<boolean> // true shared, false dismissed
}
interface HapticsDriver {
  impact(kind: HapticKind): Promise<void>
}
interface GeolocationDriver {
  current(options?: { highAccuracy?: boolean; timeout?: number }): Promise<Position>
  watch(listener: (position: Position) => void, options?: { highAccuracy?: boolean }): () => void
}
interface CameraDriver {
  capture(options?: { source?: 'camera' | 'library'; quality?: number }): Promise<Photo | null>
}
interface BiometricsDriver {
  available(): Promise<boolean>
  authenticate(options?: { reason?: string }): Promise<boolean> // false on cancel
}
```

Register a driver from a provider's `register()`, so it is in place before the `native` service is built. This one gives the Capacitor shell real haptics with [`@capacitor/haptics`](https://capacitorjs.com/docs/apis/haptics). Install it with `pnpm add @capacitor/haptics`, then create the provider with `kitr make:provider native_drivers`:

```ts
// app/providers/native_drivers_provider.ts
import { Capacitor } from '@capacitor/core'
import { Haptics, ImpactStyle, NotificationType } from '@capacitor/haptics'
import { defineProvider } from 'kitr/app'
import type { HapticKind, HapticsDriver } from 'kitr/native'

const impacts = { light: ImpactStyle.Light, medium: ImpactStyle.Medium, heavy: ImpactStyle.Heavy }
const notices = {
  success: NotificationType.Success,
  warning: NotificationType.Warning,
  error: NotificationType.Error,
}

function capacitorHaptics(): HapticsDriver {
  return {
    async impact(kind: HapticKind) {
      if (kind === 'selection') return Haptics.selectionChanged()
      if (kind in notices) return Haptics.notification({ type: notices[kind as keyof typeof notices] })
      return Haptics.impact({ style: impacts[kind as keyof typeof impacts] })
    },
  }
}

export default defineProvider({
  name: 'native-drivers',
  register(app) {
    if (Capacitor.isNativePlatform())
      app.drivers.register('haptics', capacitorHaptics(), { platform: 'mobile' })
  },
})
```

Add `() => import('#app/providers/native_drivers_provider')` to `providers` in `kitrrc.ts`. Inside the iOS or Android app, `native.haptics.name` is now `'mobile'` and `impact('success')` plays the system success pattern; in the browser the web driver still applies. A registered driver has priority 10 by default, and a higher `priority` wins when two providers register the same capability.

The Electron shell runs Node only in the main process, so a native driver there calls main over IPC. Add a channel to the IPC contract the desktop platform wrote, handle it in main with Electron's [`clipboard`](https://www.electronjs.org/docs/latest/api/clipboard) module, and wrap the client in a driver:

```ts
// app/native/electron-clipboard.ts
import { createIpcClient } from 'kitr/desktop/electron'
import type { ClipboardDriver } from 'kitr/native'

type ClipboardIpc = {
  'clipboard.read': () => string
  'clipboard.write': (text: string) => void
}

const ipc = createIpcClient<ClipboardIpc>()

export function electronClipboard(): ClipboardDriver | undefined {
  if (!ipc.available) return undefined
  return {
    readText: () => ipc.invoke('clipboard.read'),
    writeText: (text) => ipc.invoke('clipboard.write', text),
  }
}
```

```ts
// platforms/app/main.ts
import { clipboard, ipcMain } from 'electron'
import { handleIpc } from 'kitr/desktop/electron-main'

handleIpc<{ 'clipboard.read': () => string; 'clipboard.write': (text: string) => void }>(ipcMain, {
  'clipboard.read': () => clipboard.readText(),
  'clipboard.write': (_event, text) => clipboard.writeText(text),
})
// ...
```

Then set it in `config/native.ts`, as shown under [Configure](#configure). `electronClipboard()` returns `undefined` in a plain browser, so the web driver still applies to the web build. The types are under `ClipboardDriver`, `ShareDriver`, `HapticsDriver`, `GeolocationDriver`, `CameraDriver` and `BiometricsDriver` in the [API reference](/packages/native/api).

## Next steps

- [API reference](/packages/native/api)
- [Platform](/packages/platform): where the app runs, online state, deep links and the back button.
- [Auth](/packages/auth): sign-in and passkeys verified on the server.
- [Uploads](/packages/uploads): send photos from `camera.capture()` to your server.
- [Mobile](/packages/mobile): the Capacitor shell that native drivers plug into.
- [Web Share API on MDN](https://developer.mozilla.org/docs/Web/API/Web_Share_API): which browsers share files and which only share links.


# Notifications API

Source: https://kitr.dev/packages/notifications/api

Every export of `kitr/notifications`, `kitr/notifications/react`, `kitr/notifications/provider`, read from the published type definitions. The [guide](/packages/notifications) shows them in use.

## kitr/notifications

### createMemoryNotificationsDriver

```ts
function createMemoryNotificationsDriver(permission?: NotificationPermission): NotificationsDriver & {
  shown: (NotificationOptions & {
    id: string;
  })[];
  scheduled: Map<string, ScheduleOptions & {
    id: string;
  }>;
  tap(id: string): void;
};
```

For tests and the server: records what was shown, `tap(id)` simulates a tap.

### createNotifications

```ts
function createNotifications(config?: NotificationsConfig, app?: KitrApp): Notifications;
```

Build the `notifications` service. The driver is `config.driver`, else the one registered on
`app`, else the web driver in a browser or a memory driver (`unsupported`) on the server.

### createWebNotificationsDriver

```ts
function createWebNotificationsDriver(config?: {
  icon?: string;
}): NotificationsDriver;
```

Driver on the browser Notification API, with timers for scheduling. Scheduled ones are lost when
the page closes. Falls back to the service worker where the constructor is not allowed.

### notificationId

```ts
function notificationId(): string;
```

A unique id such as `n-m5x2k1qz-0`, used when `show()` or `schedule()` gets none.

### useNotifications

```ts
function useNotifications(app: KitrApp): Notifications;
```

The app's `notifications` service, outside React. Same as `app.container.use('notifications')`.

### defineConfig

```ts
const defineConfig: <const C extends NotificationsConfig>(config: C) => C;
```

Types `config/notifications.ts`. Returns the object unchanged.

### NotificationOptions

```ts
interface NotificationOptions {
  /** Your own id, so the same notification can be replaced or cancelled. Default: generated. */
  id?: string;
  /** The first line. */
  title: string;
  /** The text under the title. */
  body?: string;
  /** Where a tap should take the person, e.g. `/inbox/42`. Handed to `onTap` listeners. */
  url?: string;
  /** The image beside the text. Default: `config.icon` on the web. */
  icon?: string;
  /** Platform-specific extras passed through to the driver. */
  data?: Record<string, unknown>;
  /** Group id (Android channel, web tag). */
  channel?: string;
  /** Show without sound or vibration. */
  silent?: boolean;
}
```

What to show: a title, optional body and icon, and the `url` a tap should open.

### Notifications

```ts
interface Notifications {
  /** The active driver. */
  readonly driver: NotificationsDriver;
  /** Read the permission state without asking. */
  permission(): Promise<NotificationPermission>;
  /** Ask once; resolves to the new state. Call it from a click, browsers block unprompted asks. */
  request(): Promise<NotificationPermission>;
  /** Show now. Resolves to the notification id. */
  show(options: NotificationOptions): Promise<string>;
  /** Show later. Resolves to the id, usable with `cancel()`. */
  schedule(options: ScheduleOptions): Promise<string>;
  /** Stop a scheduled notification and close it if shown. */
  cancel(id: string): Promise<void>;
  /** Cancel every scheduled notification and close shown ones. */
  cancelAll(): Promise<void>;
  /** Ids of scheduled notifications not yet delivered. */
  pending(): Promise<string[]>;
  /** A notification was tapped (the app may have been opened by it). */
  onTap(listener: (tap: NotificationTap) => void): () => void;
}
```

The `notifications` service: permission, show, schedule, cancel and taps.

### NotificationsConfig

```ts
interface NotificationsConfig {
  /** Replace the driver the service would pick (tests, custom shells). */
  driver?: NotificationsDriver;
  /** Default icon for web notifications. */
  icon?: string;
  /** Ask for permission at boot instead of waiting for the first `request()`. Default false. */
  requestOnBoot?: boolean;
}
```

Options for `config/notifications.ts` and `createNotifications()`.

### NotificationsDriver

```ts
interface NotificationsDriver {
  /** Shown in devtools, such as `web` or `memory`. */
  name: string;
  /** Read the permission state without asking. */
  permission(): Promise<NotificationPermission>;
  /** Ask for permission; resolves to the new state. */
  request(): Promise<NotificationPermission>;
  /** Show now, replacing any notification with the same id. */
  show(options: NotificationOptions & {
    id: string;
  }): Promise<void>;
  /** Show at `options.at`, replacing any scheduled notification with the same id. */
  schedule(options: ScheduleOptions & {
    id: string;
  }): Promise<void>;
  /** Stop a scheduled notification and close it if shown. */
  cancel(id: string): Promise<void>;
  /** Cancel everything. Without it the service cancels each pending id. */
  cancelAll?(): Promise<void>;
  /** Ids scheduled and not yet shown. Without it the service answers `[]`. */
  pending?(): Promise<string[]>;
  /** Listen for taps; returns a function that removes the listener. */
  onTap(listener: (tap: NotificationTap) => void): () => void;
}
```

What a platform implements to show notifications. The service always passes an id.

### NotificationTap

```ts
interface NotificationTap {
  /** The id `show()` or `schedule()` resolved to. */
  id: string;
  /** The `url` the notification was shown with. */
  url?: string;
  /** The `data` the notification was shown with. */
  data?: Record<string, unknown>;
}
```

What a tap listener receives: the notification's id and the `url` and `data` it was shown with.

### ScheduleOptions

```ts
interface ScheduleOptions extends NotificationOptions {
  /** When to show it: a `Date` or a timestamp in milliseconds. A past time shows it at once. */
  at: Date | number;
}
```

A notification to show later.

### NotificationPermission

```ts
/** Where permission stands: `prompt` until asked, `unsupported` where there is no notification API. */
type NotificationPermission = 'granted' | 'denied' | 'prompt' | 'unsupported';
```

Where permission stands: `prompt` until asked, `unsupported` where there is no notification API.

## kitr/notifications/react

### useNotificationPermission

```ts
function useNotificationPermission(): {
  permission: NotificationPermission | 'unknown';
  request: () => Promise<NotificationPermission>;
};
```

`{ permission, request }`: the current state and a function to ask (call it from a click).

### useNotifications

```ts
function useNotifications(): Notifications;
```

The app's `notifications` service in a component.

### useNotificationTap

```ts
function useNotificationTap(handler: (tap: NotificationTap) => void): void;
```

Run a handler when a notification is tapped, typically `(tap) => tap.url && navigate(tap.url)`.

## kitr/notifications/provider

### notificationsProvider

```ts
const notificationsProvider: import("@kitr/core").KitrProvider;
```

Binds `notifications` to the platform driver (`notifications` capability) or the web
Notification API. With `requestOnBoot` it asks for permission as the app starts.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Notifications

Source: https://kitr.dev/packages/notifications

A reminder to approve an invoice, a note that an order has shipped, a nudge before a meeting: some things should reach people even when your tab is in the background. `kitr/notifications` gives you one `notifications` service to ask for permission, show a notification now or at a set time, and find out which one was tapped so the app opens the right page.

In the browser it is built on the [Notification API](https://developer.mozilla.org/docs/Web/API/Notifications_API), with timers for scheduling. kitr adds stable ids you can cancel by, a `url` carried from the notification to its tap, a React hook for the permission state, a memory driver for tests and a driver slot for native shells.

It runs in the browser and in desktop and mobile shells; on the server the service shows nothing. It covers notifications the app shows itself. Push notifications sent from your server while the app is closed need a push service (APNs, FCM or [Web Push](https://developer.mozilla.org/docs/Web/API/Push_API)) on top.

This guide follows Acme's billing screen at `app.acme.com`: Ada turns on reminders, schedules one to approve invoice `inv_1042`, and lands on that invoice when she taps it.

## Install

```sh
kitr add notifications
```

What `kitr add` does:

- Adds [Platform](/packages/platform) first when the project does not have it yet, because `notifications` requires `platform`. The `desktop` and `mobile` kits already include it.
- Installs `@kitr/notifications`.
- Adds `() => import('@kitr/notifications/provider')` to `providers` in `kitrrc.ts`.
- Adds `@kitr/notifications` to `packages` in `kitrrc.ts`.
- Writes `config/notifications.ts` (shown under [Configure](#configure)).
- Adds a `## kitr: notifications` section to `AGENTS.md`: `useNotificationPermission()` gives `{ permission, request }` and `request` is called from a click, `show({ title, url })` and `schedule({ ..., at })` resolve to an id for `cancel`, and taps are routed once near the router with `useNotificationTap`.

It adds no environment variables or scripts. `kitr add notifications` asks no questions, and no kit includes it. It is a client package, so a server-only project skips it with a warning. To preview the changes:

```sh
kitr add notifications --dry-run
```

`kitr remove notifications` removes the provider, the `packages` entry, the dependency, the `AGENTS.md` section and `config/notifications.ts`, then lists the files that still import `kitr/notifications`.

## Configure

`kitr add` writes this file:

```ts
// config/notifications.ts
import { defineConfig } from 'kitr/notifications'

export default defineConfig({
  icon: '/icon-192.png',
  // Ask from a click (browsers block unprompted asks); true asks at boot instead.
  requestOnBoot: false,
})
```

| Option | Default | Description |
| --- | --- | --- |
| `icon` | none | Icon for browser notifications that don't set their own. A path under `public/` or a full URL. |
| `requestOnBoot` | `false` | Ask for permission as the app starts in the browser. Browsers block or bury asks that don't follow a click, so leave it off for websites. |
| `driver` | registered, else the web driver | A `NotificationsDriver` that replaces the one the service would pick. For tests and custom shells. |

The service picks its driver in this order: `driver` from the config, a driver a provider registered under `notifications`, then the web driver in a browser, or a memory driver whose permission is `'unsupported'` on the server.

Point `icon` at a file that exists. The [Web](/packages/web) platform's PWA manifest uses `/icons/icon-192.png` by default, not the `/icon-192.png` that `kitr add` writes, so with `pwa` on you usually want `icon: '/icons/icon-192.png'`. A missing icon shows the notification with the browser's default image.

## Send your first notification

Ask for permission from a button, then show a notification:

```tsx
// app/features/invoices/notify-me.tsx
import { useNotificationPermission, useNotifications } from 'kitr/notifications/react'

export function NotifyMe() {
  const { permission, request } = useNotificationPermission()
  const notifications = useNotifications()
  if (permission === 'unsupported' || permission === 'denied') return null
  if (permission !== 'granted')
    return (
      <button type="button" onClick={request}>
        Turn on notifications
      </button>
    )
  return (
    <button
      type="button"
      onClick={() =>
        notifications.show({
          title: 'Invoice inv_1042 is due',
          body: 'Acme Corp, $1,280.00, due Friday',
          url: '/invoices/inv_1042',
        })
      }
    >
      Test a notification
    </button>
  )
}
```

Ada clicks **Turn on notifications**, the browser asks, and she allows it. The button changes to **Test a notification**; clicking it shows a system notification titled "Invoice inv_1042 is due" with Acme's icon. Routing the tap to `/invoices/inv_1042` is covered in [Open the right page when tapped](#open-the-right-page-when-tapped).

## Ask for permission

`useNotificationPermission()` returns `{ permission, request }`. `permission` is `'unknown'` on the first render and on the server, then one of four states:

| State | Meaning | What to show |
| --- | --- | --- |
| `'prompt'` | Not asked yet, or the person closed the prompt. | A button that calls `request`. |
| `'granted'` | Notifications will show. | Your reminder controls. |
| `'denied'` | Blocked. The page cannot ask again. | Nothing, or how to unblock it in the browser's site settings. |
| `'unsupported'` | No Notification API here, or the server. | Nothing. |

`request()` resolves to the new state, so you can act on the answer in the same handler:

```tsx
// app/features/invoices/enable-reminders.tsx
import { useNotificationPermission } from 'kitr/notifications/react'

export function EnableReminders({ onEnabled }: { onEnabled: () => void }) {
  const { permission, request } = useNotificationPermission()
  if (permission === 'denied')
    return <p>Reminders are blocked. Allow notifications for app.acme.com in your browser settings.</p>
  if (permission !== 'prompt') return null
  async function enable() {
    const state = await request()
    // => 'granted' or 'denied', or 'prompt' when Ada closed the prompt
    if (state === 'granted') onEnabled()
  }
  return (
    <button type="button" onClick={enable}>
      Remind me about due invoices
    </button>
  )
}
```

Call `request` from a click. Browsers ignore or quietly block permission prompts that no gesture started, and Safari requires one. Don't call it from an effect on page load; ask when the person does something that needs a notification.

For an installed app or a kiosk where an ask at start is expected, set `requestOnBoot: true`. The provider then calls `request()` as the app boots in the browser.

Outside React, `notifications.permission()` reads the state without asking.

## Show a notification now

`notifications.show(options)` resolves to the notification's id:

```ts
// app/features/orders/notify-shipped.ts
import type { Notifications } from 'kitr/notifications'

export async function notifyShipped(notifications: Notifications, orderId: string) {
  const id = await notifications.show({
    title: `Order ${orderId} has shipped`,
    body: 'Arriving Thursday at Acme HQ',
    url: `/orders/${orderId}`,
    data: { orderId },
  })
  // => 'n-m5x2k1qz-0' (generated)
  return id
}
```

| Option | Default | Description |
| --- | --- | --- |
| `title` | required | The first line. |
| `body` | none | The text under the title. |
| `url` | none | Where a tap should go, such as `/orders/ord_3001`. Handed to tap listeners. |
| `id` | generated | Your own id, to replace or cancel this notification later. |
| `icon` | `config.icon` | The image beside the text. |
| `data` | none | Extra values handed to tap listeners and passed to native drivers. |
| `channel` | the id | A group. On the web it is the notification's `tag`, so a new one in the same channel replaces the old. On Android it is the notification channel. |
| `silent` | `false` | Show it without sound or vibration. |

On the web, `show()` does nothing while permission is not `'granted'`, and still resolves to an id. Check `permission` before you rely on a notification being seen.

Use it for events that happen while the app is open, such as a realtime message saying an order shipped. When the app is closed, nothing on the device runs your code, so only a push service can notify.

## Replace a notification

Give a notification your own `id` to update it instead of stacking a second one. Showing the same id again closes the first:

```ts
// app/features/orders/orders-export.ts
import type { Notifications } from 'kitr/notifications'

export async function reportExport(notifications: Notifications, done: number, total: number) {
  await notifications.show({
    id: 'orders-export',
    title: done < total ? `Exporting orders: ${done} of ${total}` : 'Orders export ready',
    url: done < total ? undefined : '/orders/exports',
    silent: done < total,
  })
}
```

Each call replaces the last, so Ada sees one notification that ends as "Orders export ready". `channel` does the same for notifications with different ids: the browser keeps one notification per `tag`.

## Schedule a notification

`notifications.schedule(options)` takes everything `show` takes plus `at`, a `Date` or a timestamp in milliseconds, and resolves to the id:

```tsx
// app/features/invoices/remind-later.tsx
import { useNotifications } from 'kitr/notifications/react'

export function RemindLater({ invoiceId }: { invoiceId: string }) {
  const notifications = useNotifications()
  async function remind() {
    const id = await notifications.schedule({
      id: `approve-${invoiceId}`,
      title: `Approve invoice ${invoiceId}`,
      body: 'Grace is waiting on your approval',
      url: `/invoices/${invoiceId}`,
      at: Date.now() + 60 * 60 * 1000,
    })
    // => 'approve-inv_1042'
    return id
  }
  return (
    <button type="button" onClick={remind}>
      Remind me in an hour
    </button>
  )
}
```

A time in the past shows the notification straight away. Scheduling an id that is already scheduled replaces it, so `approve-inv_1042` can only fire once. An invalid `at`, such as `new Date('next week')` or `NaN`, rejects:

```ts
// app/features/invoices/bad-reminder.ts
import type { Notifications } from 'kitr/notifications'

export async function badReminder(notifications: Notifications) {
  await notifications.schedule({ title: 'Approve invoice inv_1042', at: new Date('next week') })
  // throws Error: [kitr/notifications] schedule() needs a valid `at`, got Invalid Date
}
```

> **Warning**
> On the web, scheduled notifications live in a timer inside the page. They are lost when the tab closes or reloads, and browsers slow timers in background tabs. For a reminder that must arrive, schedule it on your server and deliver it with Web Push, or use a native driver that hands it to the operating system.

The web driver waits in steps, so a reminder 40 days out does not fire early when it passes the browser's 24.8-day timer limit.

## Cancel notifications

Cancel by the id that `show` or `schedule` resolved to, list what is still waiting, or clear everything:

```ts
// app/features/invoices/approve.ts
import type { Notifications } from 'kitr/notifications'

export async function onInvoiceApproved(notifications: Notifications, invoiceId: string) {
  await notifications.cancel(`approve-${invoiceId}`)
  const waiting = await notifications.pending()
  // => ['approve-inv_1043'], the ids scheduled and not yet shown
  return waiting
}

export async function onSignOut(notifications: Notifications) {
  await notifications.cancelAll()
}
```

`cancel(id)` stops a scheduled notification and, on the web, closes it if it is on screen. `cancelAll()` does both for every notification this page showed or scheduled. Call it when someone signs out, so Linus doesn't get Ada's reminders on a shared computer. `pending()` lists only scheduled notifications that haven't fired; shown ones are not in it.

## Open the right page when tapped

`useNotificationTap(handler)` calls `handler` with `{ id, url, data }` whenever a notification is clicked. Mount it once, inside the router, so every tap navigates:

```tsx
// app/components/notification-router.tsx
import { useNotificationTap } from 'kitr/notifications/react'
import { useNavigate } from 'kitr/router'
import { useCallback } from 'react'

export function NotificationRouter() {
  const navigate = useNavigate()
  const onTap = useCallback(
    (tap: { id: string; url?: string }) => {
      if (tap.url) void navigate({ to: tap.url })
    },
    [navigate],
  )
  useNotificationTap(onTap)
  return null
}
```

```tsx
// app/routes/__root.tsx
import { createRootRoute, Outlet } from 'kitr/router'
import { NotificationRouter } from '#app/components/notification-router'

export const Route = createRootRoute({
  component: () => (
    <>
      <NotificationRouter />
      <Outlet />
    </>
  ),
})
```

Ada clicks "Approve invoice inv_1042", the browser focuses the Acme tab, closes the notification and the app moves to `/invoices/inv_1042`. Wrapping the handler in `useCallback` keeps the hook from re-subscribing on every render.

Don't mount `useNotificationTap` in each page that shows notifications: a tap on a notification from another page would then go nowhere. One listener near the router handles them all.

Outside React, `notifications.onTap(listener)` returns a function that removes the listener:

```ts
// app/features/invoices/track-taps.ts
import type { Notifications } from 'kitr/notifications'

export function trackReminderTaps(notifications: Notifications, record: (id: string) => void) {
  return notifications.onTap((tap) => {
    if (tap.id.startsWith('approve-')) record(tap.id)
  })
}
```

## Show notifications on Chrome for Android

Chrome on Android does not let a page construct a `Notification`. When the constructor throws and a [service worker](https://developer.mozilla.org/docs/Web/API/ServiceWorkerRegistration/showNotification) controls the page, the web driver shows the notification through the worker instead. Turn on `pwa` in the [Web](/packages/web) platform so the app has one:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  // ...
  platforms: {
    site: web({ mode: 'spa', pwa: true }),
  },
})
```

Taps on those notifications reach the worker's `notificationclick` event, not `onTap`. The notification's `data` holds `{ id, url, data }`, so a custom worker can open `url`. Without a controlling service worker, `show()` on Chrome for Android rejects with the browser's `TypeError: Illegal constructor`.

## Use it outside React

Read the service from the app's container. `useNotifications(app)` from `kitr/notifications` does the same thing:

```ts
// app/features/orders/on-shipped.ts
import type { KitrApp } from 'kitr/app'
import { useNotifications } from 'kitr/notifications'

export async function onOrderShipped(app: KitrApp, orderId: string) {
  const notifications = useNotifications(app) // same as app.container.use('notifications')
  if ((await notifications.permission()) !== 'granted') return
  await notifications.show({ title: `Order ${orderId} has shipped`, url: `/orders/${orderId}` })
}
```

To build a service with no app, call `createNotifications(config)`. In a browser it uses the web driver; in Node, the memory driver with `'unsupported'` permission. When the [Devtools](/packages/devtools) provider is installed, the service logs each permission answer, show, schedule and tap under `notifications`.

## Where notifications come from

| Where it runs | Driver | Scheduled notifications |
| --- | --- | --- |
| Browser | `createWebNotificationsDriver()`, the Notification API | Fire only while the page is open. |
| Chrome for Android | The same driver, through the service worker | The same. |
| Desktop and mobile shells | The web driver inside the webview, unless a provider registers one | The same, until a native driver is registered. |
| Server | Memory driver, permission `'unsupported'` | Nothing is shown. |

Today [Desktop](/packages/desktop) and [Mobile](/packages/mobile) register only `platform` and `storage` drivers. To hand notifications to the operating system, so scheduled ones fire with the app closed, register a `notifications` driver as shown under [Extend](#extend).

## Errors

| Error | When | What to do |
| --- | --- | --- |
| ``[kitr/notifications] schedule() needs a valid `at` `` | `at` is an invalid `Date` or `NaN`. | Pass a `Date` or a timestamp in milliseconds. |
| `TypeError: Illegal constructor` (browser) | Chrome for Android, with no service worker controlling the page. | Turn on `pwa` in the web platform. |

A `show()` without permission is not an error: it resolves and shows nothing. A denied permission is a state, not an exception.

## Testing

`createMemoryNotificationsDriver(permission)` records everything and shows nothing. Its permission starts at the state you pass (default `'granted'`); `request()` turns `'prompt'` into `'granted'` and leaves every other state as it is. It adds three things to the driver:

| Member | Description |
| --- | --- |
| `shown` | Every notification passed to `show`, with its id. |
| `scheduled` | A `Map` of id to the scheduled notification, emptied by `cancel` and `cancelAll`. |
| `tap(id)` | Simulates a tap on a shown or scheduled notification, calling every tap listener with its `url` and `data`. |

Hand it to the app through `config.notifications.driver`:

```tsx
// app/features/invoices/remind-later.test.tsx
import { fireEvent, screen, waitFor } from '@testing-library/react'
import { createMemoryNotificationsDriver } from 'kitr/notifications'
import { notificationsProvider } from 'kitr/notifications/provider'
import { useNotificationTap } from 'kitr/notifications/react'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { describe, expect, it, vi } from 'vitest'
import { EnableReminders } from './enable-reminders'
import { RemindLater } from './remind-later'

describe('invoice reminders', () => {
  it('asks for permission from the button', async () => {
    const driver = createMemoryNotificationsDriver('prompt')
    const app = await createTestApp({
      providers: [notificationsProvider],
      config: { notifications: { driver } },
    })
    const onEnabled = vi.fn()
    renderWithKitr(<EnableReminders onEnabled={onEnabled} />, { app })
    fireEvent.click(await screen.findByRole('button', { name: 'Remind me about due invoices' }))
    await waitFor(() => expect(onEnabled).toHaveBeenCalled())
    expect(await driver.permission()).toBe('granted')
  })

  it('schedules one reminder per invoice and routes the tap', async () => {
    const driver = createMemoryNotificationsDriver()
    const app = await createTestApp({
      providers: [notificationsProvider],
      config: { notifications: { driver } },
    })
    const opened: string[] = []
    function Taps() {
      useNotificationTap((tap) => tap.url && opened.push(tap.url))
      return null
    }
    renderWithKitr(
      <>
        <Taps />
        <RemindLater invoiceId="inv_1042" />
      </>,
      { app },
    )
    const button = screen.getByRole('button', { name: 'Remind me in an hour' })
    fireEvent.click(button)
    fireEvent.click(button)
    await waitFor(() => expect(driver.scheduled.size).toBe(1))
    expect(driver.scheduled.get('approve-inv_1042')).toMatchObject({
      title: 'Approve invoice inv_1042',
      url: '/invoices/inv_1042',
    })
    driver.tap('approve-inv_1042')
    expect(opened).toEqual(['/invoices/inv_1042'])
  })
})
```

To test code that takes the service directly, build one with `createNotifications`:

```ts
// app/features/invoices/approve.test.ts
import { createMemoryNotificationsDriver, createNotifications } from 'kitr/notifications'
import { expect, it } from 'vitest'
import { onInvoiceApproved } from './approve'

it('cancels the reminder once the invoice is approved', async () => {
  const driver = createMemoryNotificationsDriver()
  const notifications = createNotifications({ driver })
  await notifications.schedule({ id: 'approve-inv_1042', title: 'Approve', at: Date.now() + 1000 })
  await notifications.schedule({ id: 'approve-inv_1043', title: 'Approve', at: Date.now() + 1000 })
  expect(await onInvoiceApproved(notifications, 'inv_1042')).toEqual(['approve-inv_1043'])
})
```

To test the web driver itself, stub the global `Notification` class with `vi.stubGlobal('Notification', ...)` and use fake timers for `schedule`.

## Extend

A driver implements `NotificationsDriver`. The service generates ids before it calls `show` and `schedule`, so a driver always receives one:

```ts
interface NotificationsDriver {
  name: string
  permission(): Promise<NotificationPermission> // 'granted' | 'denied' | 'prompt' | 'unsupported'
  request(): Promise<NotificationPermission>
  show(options: NotificationOptions & { id: string }): Promise<void>
  schedule(options: ScheduleOptions & { id: string }): Promise<void>
  cancel(id: string): Promise<void>
  cancelAll?(): Promise<void> // optional: the service falls back to cancel() on each pending id
  pending?(): Promise<string[]> // optional: the service answers [] without it
  onTap(listener: (tap: NotificationTap) => void): () => void
}
```

This driver hands notifications to iOS and Android through [`@capacitor/local-notifications`](https://capacitorjs.com/docs/apis/local-notifications), so scheduled ones fire with the app closed. Capacitor needs whole-number ids, so the driver hashes kitr's string id and keeps the original in `extra`. Install it with `pnpm add @capacitor/local-notifications`, then create the provider with `kitr make:provider notifications_driver`:

```ts
// app/providers/notifications_driver_provider.ts
import { Capacitor } from '@capacitor/core'
import { LocalNotifications } from '@capacitor/local-notifications'
import { defineProvider } from 'kitr/app'
import type { NotificationPermission, NotificationsDriver } from 'kitr/notifications'

const numeric = (id: string) => {
  let hash = 0
  for (const char of id) hash = (hash * 31 + char.charCodeAt(0)) | 0
  return Math.abs(hash)
}
const toState = (display: string): NotificationPermission =>
  display === 'granted' ? 'granted' : display === 'denied' ? 'denied' : 'prompt'

function capacitorNotifications(): NotificationsDriver {
  const post = (o: Parameters<NotificationsDriver['show']>[0], at?: Date) =>
    LocalNotifications.schedule({
      notifications: [
        {
          id: numeric(o.id),
          title: o.title,
          body: o.body ?? '',
          channelId: o.channel,
          schedule: at ? { at } : undefined,
          extra: { id: o.id, url: o.url, data: o.data },
        },
      ],
    }).then(() => undefined)
  return {
    name: 'capacitor',
    permission: async () => toState((await LocalNotifications.checkPermissions()).display),
    request: async () => toState((await LocalNotifications.requestPermissions()).display),
    show: (o) => post(o),
    schedule: (o) => post(o, new Date(o.at)),
    cancel: (id) => LocalNotifications.cancel({ notifications: [{ id: numeric(id) }] }),
    pending: async () =>
      (await LocalNotifications.getPending()).notifications.map((n) => String(n.extra?.id ?? n.id)),
    onTap(listener) {
      const handle = LocalNotifications.addListener('localNotificationActionPerformed', (event) => {
        const extra = event.notification.extra ?? {}
        listener({ id: extra.id ?? String(event.notification.id), url: extra.url, data: extra.data })
      })
      return () => void handle.then((h) => h.remove())
    },
  }
}

export default defineProvider({
  name: 'notifications-driver',
  register(app) {
    if (Capacitor.isNativePlatform())
      app.drivers.register('notifications', capacitorNotifications(), { platform: 'mobile' })
  },
})
```

Add `() => import('#app/providers/notifications_driver_provider')` to `providers` in `kitrrc.ts`. Inside the iOS or Android app, `notifications.driver.name` is now `'capacitor'` and Ada's reminder fires even after she closes the app; in the browser, the web driver still applies. The `NotificationsDriver`, `NotificationOptions` and `NotificationTap` types are in the [API reference](/packages/notifications/api).

## Next steps

- [API reference](/packages/notifications/api)
- [Notifications API on MDN](https://developer.mozilla.org/docs/Web/API/Notifications_API): what each browser supports.
- [Web](/packages/web): the `pwa` option that adds the service worker Chrome for Android needs.
- [Realtime](/packages/realtime): learn about a shipped order while the app is open, then show a notification.
- [Jobs](/packages/jobs): schedule reminders on the server, where they survive a closed tab.
- [Mobile](/packages/mobile): the Capacitor shell that a native driver plugs into.


# Offline API

Source: https://kitr.dev/packages/offline/api

Every export of `kitr/offline`, `kitr/offline/react`, `kitr/offline/provider`, read from the published type definitions. The [guide](/packages/offline) shows them in use.

## kitr/offline

### bindOnlineManager

```ts
function bindOnlineManager(platform: {
  isOnline(): boolean;
  onOnline(l: (online: boolean) => void): () => void;
}): void;
```

Let TanStack Query's online state follow the platform driver (native shells report it better than `navigator.onLine`).

### createOffline

```ts
function createOffline(client: QueryClient, config?: OfflineConfig, app?: KitrApp): Offline;
```

Build the offline service for a QueryClient: it saves successful queries and paused mutations
to storage on a throttle (and when the page is hidden), and can restore them into the client.

### useOffline

```ts
function useOffline(app: KitrApp): Offline;
```

The `offline` service from an app's container, for code outside React. Bound on the client only.

### defineConfig

```ts
const defineConfig: <const C extends OfflineConfig>(config: C) => C;
```

Type-checks `config/offline.ts`. Returns the object unchanged.

### Offline

```ts
interface Offline {
  /** Load a stored snapshot into the client, if fresh. Resolves with whether one was found. */
  restore(): Promise<boolean>;
  /** Write the current cache now (the provider does it on a throttle). */
  persist(): void;
  /** Forget the snapshot. */
  clear(): void;
  /** Mutations waiting for the network. */
  pendingMutations(): number;
  /** Whether TanStack Query's `onlineManager` currently says online. */
  isOnline(): boolean;
  /** Called after a restore, after each throttled save, and when online state changes. Returns an unsubscribe function. */
  subscribe(listener: () => void): () => void;
  /** True once `restore()` loaded a snapshot into the client. */
  readonly restored: boolean;
}
```

The `offline` service: restores and saves the query cache snapshot and reports network state.

### OfflineConfig

```ts
interface OfflineConfig {
  /** Storage key for the cache snapshot. Default `kitr:query-cache`. */
  key?: string;
  /** Milliseconds a snapshot stays usable. Default 24 hours. */
  maxAge?: number;
  /** Persist only queries whose key passes; default: every successful query. */
  include?: (queryKey: QueryKey) => boolean;
  /** Milliseconds to wait after a change before writing. Default 1000. */
  throttle?: number;
  /** Where the snapshot lives. Default: the app's local storage driver (native on desktop/mobile). */
  storage?: StorageDriver;
  /** A string that invalidates old snapshots when the data shape changes (app version). */
  buster?: string;
}
```

Options for `config/offline.ts`: how long, where and what of the query cache is kept on the device.

## kitr/offline/react

### useOffline

```ts
function useOffline(): {
  online: boolean;
  pending: number;
  restored: boolean;
  clear: () => void;
  persist: () => void;
};
```

`{ online, pending, restored }`: whether the network is up, how many mutations wait for it,
and whether the cache came from a stored snapshot. Hydration-safe: the server says online.

## kitr/offline/provider

### offlineProvider

```ts
const offlineProvider: import("@kitr/core").KitrProvider;
```

Persists the query cache and paused mutations, restores them before the first render and
replays the mutations when the network returns (TanStack Query resumes paused mutations on
its own once `onlineManager` says online). Put it after the query provider in kitrrc.ts.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Offline

Source: https://kitr.dev/packages/offline

A train goes into a tunnel, the warehouse wifi drops, the app is reopened on a plane. Without help, every screen turns into a spinner or an error. `kitr/offline` keeps a copy of the data your app already loaded on the device and puts it back before the first render, so the app opens with the last known data. Changes made with no connection wait in a queue and are sent when the network returns.

It is built on [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode)'s own network mode and its [dehydrate and hydrate](https://tanstack.com/query/latest/docs/framework/react/reference/hydration) functions, and stores the snapshot through [Storage](/packages/storage), so desktop and mobile apps keep it in the native store. kitr adds the throttled save, the restore at boot, version-based invalidation and a `useOffline()` hook for a status line.

It runs in the browser and in desktop and mobile shells, never on the server. It keeps **data** available offline, not the app itself: to open a web app with no connection, also make it installable with the [Web](/packages/web) platform's PWA option.

This guide follows Linus, who visits Acme's customers with a tablet: he opens the orders list, loses the connection in a basement, takes a new order for Grace, and the order reaches the server when he is back upstairs.

## When to use it

Use `kitr/offline` to keep **server data** you loaded with [Query](/packages/query) usable with no connection: lists, details, the signed-in user. It saves the query cache as a whole and needs no change to your queries.

Use [Storage](/packages/storage) for values the device itself owns, such as preferences and drafts. Storage items are always there; the offline snapshot is a cache that can expire, be busted by a new version and be cleared on sign-out.

## Install

```sh
kitr add offline
```

What `kitr add` does:

- Adds [Query](/packages/query) and [Storage](/packages/storage) first, when the project doesn't have them, because `offline` requires both.
- Installs `@kitr/offline`.
- Adds `() => import('@kitr/offline/provider')` to `providers` in `kitrrc.ts`, after the query and storage providers.
- Adds `@kitr/offline` to `packages` in `kitrrc.ts`.
- Writes `config/offline.ts` (shown under [Configure](#configure)).
- Adds `VITE_APP_VERSION` to the public variables in `app/env.ts` as `e.string({ default: '0.0.0' })`, and `VITE_APP_VERSION=0.0.0` to `.env.example` (and to `.env` when it exists).
- Adds a `## kitr: offline` section to `AGENTS.md`: successful queries are persisted and restored before the first render, mutations made offline pause and replay on reconnect, give mutations a `mutationKey` and an optimistic `onMutate`, and use `useOffline()` from `kitr/offline/react` for a status line.

`kitr add offline` asks no questions and adds no scripts. It is a client package, so in a server-only project it prints `offline is a client package; this project is server-only. Skipping.` and changes nothing. No kit includes it.

`kitr remove offline` removes the provider, the `packages` entry, the dependency and the `AGENTS.md` section, deletes `config/offline.ts`, and lists the files that still import `kitr/offline`. It leaves `VITE_APP_VERSION` in `app/env.ts` and `.env.example`, and leaves Query and Storage installed.

## Configure

`kitr add offline` writes this file:

```ts
// config/offline.ts
import { defineConfig } from 'kitr/offline'
import { env } from '#app/env'

export default defineConfig({
  maxAge: 24 * 60 * 60 * 1000,
  // include: (key) => key[0] !== 'search', // leave volatile queries out of the snapshot
  buster: env.VITE_APP_VERSION, // a new version drops old snapshots
})
```

| Option | Default | Description |
| --- | --- | --- |
| `maxAge` | `86_400_000` (24 hours) | How long a saved snapshot stays usable, in milliseconds. An older one is deleted instead of restored. |
| `include` | every successful query | `(queryKey) => boolean`. Only queries that return `true` are saved. Queries that failed or never loaded are never saved. |
| `buster` | `undefined` | Any string. A snapshot saved with a different `buster` is deleted instead of restored. Set it to the app version. |
| `throttle` | `1000` | Milliseconds to wait after a cache change before saving. Changes in that window are saved in one write. |
| `key` | `'kitr:query-cache'` | The storage key the snapshot is saved under. The storage `prefix` is not added. |
| `storage` | the app's local storage driver | A `StorageDriver` from [Storage](/packages/storage). The default is `localStorage` in a browser and the native store on desktop and mobile. |

| Variable | Used for |
| --- | --- |
| `VITE_APP_VERSION` | The `buster`. A public variable, so it ships to the browser. Defaults to `0.0.0`. |

`VITE_APP_VERSION` doesn't change on its own. Set it when you build, so every release drops the snapshots of the last one:

```sh
VITE_APP_VERSION=$(git rev-parse --short HEAD) kitr build
```

The provider runs only when the app's environment is `client`. In `register()` it binds the `offline` service in the container. In `boot()` it binds TanStack's online state to [Platform](/packages/platform) when that is installed, then restores the snapshot. Because providers boot in order, the cache is filled before your first render.

### Keep queries in memory as long as the snapshot

TanStack Query removes a query from memory five minutes after the last component using it unmounts (its `gcTime`). A removed query isn't in the next snapshot, so with the defaults a list Linus hasn't opened in five minutes is gone from the device even though `maxAge` is 24 hours. Raise `gcTime` in `config/query.ts` to match `maxAge`:

```ts
// config/query.ts
import { defineConfig } from 'kitr/query'

export default defineConfig({
  staleTime: 30_000,
  defaultOptions: {
    queries: { gcTime: 24 * 60 * 60 * 1000 },
  },
})
```

## Show cached data with no connection

Nothing changes in your queries. A query that loaded once is saved, and the next time the app starts it is in the cache before the page renders:

```tsx
// app/routes/orders.tsx
import { createFileRoute } from '@tanstack/react-router'
import { defineQuery, useQuery } from 'kitr/query'

interface Order {
  id: string
  customer: string
  total: number
}

export const ordersQuery = defineQuery({
  key: () => ['orders', 'list'],
  fetch: async (_input, { signal }): Promise<Order[]> => {
    const res = await fetch('https://api.acme.com/orders', { signal })
    return (await res.json()) as Order[]
  },
})

export const Route = createFileRoute('/orders')({
  component: OrdersPage,
})

function OrdersPage() {
  const { data: orders, isPending, fetchStatus } = useQuery(ordersQuery.options())
  if (isPending) return <p>Loading orders…</p>
  return (
    <>
      {fetchStatus === 'paused' && <p>Offline. Showing the last orders loaded.</p>}
      <ul>
        {orders?.map((order) => (
          <li key={order.id}>
            {order.customer}: ${order.total}
          </li>
        ))}
      </ul>
    </>
  )
}
```

Open `/orders` with the network on and wait a second for the snapshot to be written. Close the tab, set the browser's devtools to **Offline**, and open the app again (as an installed PWA, or in the desktop or mobile shell). The list shows Ada's and Grace's orders at once, with "Offline. Showing the last orders loaded." above it, instead of "Loading orders…".

Two things happened. At boot the provider restored the snapshot into the query cache, so `isPending` was already `false`. Then TanStack tried to refetch the stale data, saw it was offline, and paused the fetch instead of failing it: `fetchStatus` is `'paused'` and the cached data stays. When the network returns, the paused fetch runs and the list updates.

The snapshot in storage is one JSON string:

```text
kitr:query-cache  {"at":1731000000000,"buster":"1.4.0","state":{"mutations":[],"queries":[{"queryKey":["orders","list"],...}]}}
```

## Show the connection status

`useOffline()` from `kitr/offline/react` gives a component the network state, the number of changes waiting to be sent, and whether the cache came from a snapshot:

```tsx
// app/components/connection-status.tsx
import { useOffline } from 'kitr/offline/react'

export function ConnectionStatus() {
  const { online, pending, restored } = useOffline()
  if (!online) return <p role="status">Offline. {pending} change(s) will be sent later.</p>
  if (pending > 0) return <p role="status">Sending {pending} change(s)…</p>
  if (restored) return <p role="status">Showing saved data while we refresh.</p>
  return null
}
```

| Field | Type | Description |
| --- | --- | --- |
| `online` | `boolean` | What TanStack Query's `onlineManager` says. Follows [Platform](/packages/platform) when it is installed. |
| `pending` | `number` | Mutations paused while waiting for the network. |
| `restored` | `boolean` | `true` once a snapshot was loaded into the cache at boot. It stays `true` for the session. |
| `clear` | `() => void` | Delete the saved snapshot. |
| `persist` | `() => void` | Save the cache now instead of after the throttle. |

The hook re-renders after a restore, after each save, and when the network goes up or down. Put `<ConnectionStatus />` in the layout so it shows on every page.

On the server the provider binds nothing, so `useOffline()` throws `[kitr] No binding named "offline". Did you add the package that provides it?` during server rendering. In a server-rendered app, render the component that calls it only on the client.

## Choose what to save

`include` gets each successful query's key and decides whether it goes in the snapshot. Leave out data that is cheap to refetch, changes every second, or shouldn't stay on the device:

```ts
// config/offline.ts
import { defineConfig } from 'kitr/offline'
import { env } from '#app/env'

const neverSaved = new Set(['search', 'notifications', 'billing'])

export default defineConfig({
  maxAge: 24 * 60 * 60 * 1000,
  include: (key) => !neverSaved.has(String(key[0])),
  buster: env.VITE_APP_VERSION,
})
```

With this config, `['orders', 'list']` and `['projects', 'detail', 'prj_7']` are saved; `['search', 'Grace']` and `['billing', 'invoices']` are not. Keys from `createKeys('orders')` in `kitr/app` always start with the resource name, so the first element is a reliable switch.

Smaller snapshots also save faster. Every save writes the whole snapshot as one string, and `localStorage` has a limit of about 5 MB per origin. When a write fails, the error is logged as `persist failed` and the app keeps running with no saved copy.

## Keep private data off the shared device

The snapshot is plain JSON in local storage or the native store. Anyone with the device can read it. Clear it when someone signs out, along with the in-memory cache:

```tsx
// app/components/sign-out-button.tsx
import { useQueryClient } from 'kitr/query'
import { useOffline } from 'kitr/offline/react'

export function SignOutButton({ onSignedOut }: { onSignedOut: () => void }) {
  const { clear } = useOffline()
  const queryClient = useQueryClient()

  return (
    <button
      type="button"
      onClick={() => {
        queryClient.clear()
        clear()
        onSignedOut()
      }}
    >
      Sign out
    </button>
  )
}
```

Clear the query cache first. `clear()` deletes the stored snapshot, but the next cache change saves a new one, so an uncleared cache would be written straight back.

> **Warning**
> Never let tokens, card numbers or other secrets into the snapshot. Leave such queries out with `include`, and keep tokens in [Secure storage](/packages/secure-storage). On a shared computer, anything in the snapshot survives until it expires or someone signs out.

## Drop old snapshots when you deploy

When a release changes the shape of your data, last week's snapshot would hand new code old data. `buster` prevents that: a snapshot saved with another `buster` is deleted at boot instead of restored. The generated config uses `VITE_APP_VERSION`:

```ts
// app/env.ts
import { createEnv, env as e } from 'kitr/env'

export const env = createEnv({
  public: {
    VITE_APP_VERSION: e.string({ default: '0.0.0' }),
  },
})
```

```sh
# .env.production
VITE_APP_VERSION=1.5.0
```

Linus's tablet holds a snapshot saved by `1.4.0`. After the `1.5.0` update the provider finds it, sees `"buster":"1.4.0"`, deletes it, and the app loads fresh data. Paused mutations in that snapshot are deleted with it, so ship releases that change mutation inputs only when you can afford to lose queued changes, or keep the old `buster`.

## Expire snapshots after a time

`maxAge` is measured from when the snapshot was last saved. A snapshot older than `maxAge` is deleted at boot instead of restored. One saved exactly `maxAge` milliseconds ago still restores:

```ts
// config/offline.ts
import { defineConfig } from 'kitr/offline'
import { env } from '#app/env'

export default defineConfig({
  // A field team works for a week between syncs.
  maxAge: 7 * 24 * 60 * 60 * 1000,
  buster: env.VITE_APP_VERSION,
})
```

Since every cache change saves the snapshot again, an app that is used every day never hits `maxAge`. It matters for an app left closed: after a week with this config, Linus's tablet opens with an empty cache and loads everything fresh. Match `gcTime` in `config/query.ts` to the new `maxAge`, as [Configure](#keep-queries-in-memory-as-long-as-the-snapshot) shows.

Restored data keeps the time it was fetched, so it counts as stale by your `staleTime` and is refetched as soon as a component uses it and the network is up.

## Queue changes while offline

Mutations need no change either. TanStack Query's default `networkMode: 'online'` pauses a mutation that starts with no connection, instead of running it and failing. The provider saves paused mutations in the snapshot, and TanStack sends them when the network returns.

Give each mutation a `mutationKey`, so it can be replayed after a reload (next section), and an optimistic `onMutate`, so the screen shows the change while it waits:

```ts
// app/features/orders/use-create-order.ts
import { defineMutation, useKitrMutation, useQueryClient } from 'kitr/query'

export interface Order {
  id: string
  customer: string
  total: number
}

export const createOrder = defineMutation({
  mutate: async (input: { customer: string; total: number }): Promise<Order> => {
    const res = await fetch('https://api.acme.com/orders', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(input),
    })
    return (await res.json()) as Order
  },
  effects: { invalidate: [['orders', 'list']] },
})

export function useCreateOrder() {
  const queryClient = useQueryClient()
  return useKitrMutation(createOrder, {
    mutationKey: ['orders', 'create'],
    onMutate: async (input) => {
      await queryClient.cancelQueries({ queryKey: ['orders', 'list'] })
      const previous = queryClient.getQueryData<Order[]>(['orders', 'list'])
      const draft: Order = { id: `draft_${Date.now()}`, ...input }
      queryClient.setQueryData<Order[]>(['orders', 'list'], (orders = []) => [...orders, draft])
      return { previous }
    },
    onError: (_error, _input, context) => {
      const previous = (context as { previous?: Order[] } | undefined)?.previous
      if (previous) queryClient.setQueryData(['orders', 'list'], previous)
    },
  })
}
```

```tsx
// app/features/orders/new-order-button.tsx
import { useCreateOrder } from './use-create-order'

export function NewOrderButton() {
  const createOrder = useCreateOrder()
  return (
    <button type="button" onClick={() => createOrder.mutate({ customer: 'Grace', total: 240 })}>
      New order for Grace
    </button>
  )
}
```

In the basement, Linus taps the button. Grace's order appears in the list at once, `createOrder.isPaused` is `true`, and `<ConnectionStatus />` reads "Offline. 1 change(s) will be sent later." Back upstairs, TanStack sends the request, the `effects` refetch the list, and the status line disappears.

Don't catch the offline case yourself and retry with `setTimeout`: the mutation is already queued, and a second attempt sends the order twice.

## Replay queued changes after a reload

A paused mutation that is restored from a snapshot is data only: its function didn't survive the reload. Register the function for each `mutationKey` with TanStack's [`setMutationDefaults`](https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientsetmutationdefaults). TanStack copies the defaults into a mutation when it is restored, so they must be set **before** the offline provider restores the snapshot. Do it in the `register()` of a provider, which runs before any provider boots:

```ts
// app/providers/offline-mutations.ts
import { defineProvider } from 'kitr/app'
import { createOrder } from '#app/features/orders/use-create-order'

export default defineProvider({
  name: 'offline-mutations',
  register(app) {
    if (!app.isClient) return
    const queryClient = app.container.use('queryClient')
    queryClient.setMutationDefaults(['orders', 'create'], createOrder.options({ queryClient }))
  },
  async boot(app) {
    if (!app.isClient) return
    await app.container.use('queryClient').resumePausedMutations()
  },
})
```

List it after the offline provider, so its `boot()` runs once the snapshot is restored:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'

export default defineKitrConfig({
  providers: [
    () => import('@kitr/query/provider'),
    () => import('@kitr/storage/provider'),
    () => import('@kitr/offline/provider'),
    () => import('#app/providers/offline-mutations'),
    // ...
  ],
  // ...
})
```

`createOrder.options({ queryClient })` returns the mutation function and the cache effects, so a replayed order behaves like one sent from the button. `resumePausedMutations()` sends restored mutations as soon as the app starts online; while offline it leaves them paused. Without that call, TanStack sends them on the next focus or reconnect event.

Don't set the defaults in `boot()` or in a component. By then the mutation was restored without a function, and it fails when it resumes with TanStack's `No mutationFn found` error.

## Save and restore by hand

The provider saves on its own: one second after the last cache change, and right away when the page is hidden or closed, so a change made just before Linus locks the tablet is not lost. Outside React, the `offline` service gives you the same controls:

```ts
// app/features/sync/sync-now.ts
import { useOffline } from 'kitr/offline'
import { app } from '#app/app'

export async function resetDeviceCache() {
  const offline = useOffline(app)

  offline.persist() // write the snapshot now
  offline.pendingMutations() // => 0
  offline.isOnline() // => true
  offline.restored // => true when the app started from a snapshot

  offline.clear() // delete the snapshot
  await offline.restore() // => false, nothing left to restore
}
```

`restore()` resolves to `true` when it loaded a snapshot. A snapshot that isn't valid JSON, has the wrong shape, another `buster`, or is older than `maxAge` is deleted, and `restore()` resolves to `false` without throwing, so a corrupt snapshot never stops the app from booting. `subscribe(listener)` calls `listener` after a restore, after each throttled save and on every online change, and returns an unsubscribe function.

To use the service with a `QueryClient` you build yourself, outside the provider, call `createOffline(client, config)`:

```ts
// scripts/warm-cache.ts
import { createOffline } from 'kitr/offline'
import { QueryClient } from 'kitr/query'
import { createMemoryStorageDriver } from 'kitr/storage'

const storage = createMemoryStorageDriver()
const client = new QueryClient()
client.setQueryData(['orders', 'list'], [{ id: 'ord_1042', customer: 'Ada', total: 129 }])

createOffline(client, { storage }).persist()
JSON.parse(storage.get('kitr:query-cache') ?? '{}').state.queries.length // => 1
```

## Follow the platform's online state

By default TanStack Query listens to the browser's `online` and `offline` events. Native shells know the network better than `navigator.onLine`, so when [Platform](/packages/platform) is installed, the provider calls `bindOnlineManager` with the `platform` service and TanStack follows the platform driver instead. You don't call it yourself in a kitr app.

Outside the provider, for example in a test, pass anything with `isOnline()` and `onOnline(listener)`:

```ts
// test/support/network.ts
import { bindOnlineManager } from 'kitr/offline'

let setNetwork: (online: boolean) => void = () => {}

bindOnlineManager({
  isOnline: () => true,
  onOnline: (listener) => {
    setNetwork = listener
    return () => {}
  },
})

export const goOffline = () => setNetwork(false)
export const goOnline = () => setNetwork(true)
```

TanStack's `onlineManager` is global, so the binding applies to every `QueryClient` in the page.

## Testing

The provider only runs when the app's environment is `client`, so pass `environment: 'client'` to `createTestApp`. Give it an in-memory storage driver in config, seed a snapshot with `createOffline`, and boot: the cache holds the seeded data before any test code runs. TanStack's `onlineManager` lets you take the app offline:

```ts
// app/features/orders/offline.test.ts
import { createOffline } from 'kitr/offline'
import offlineProvider from 'kitr/offline/provider'
import { onlineManager, QueryClient } from 'kitr/query'
import queryProvider from 'kitr/query/provider'
import { createMemoryStorageDriver } from 'kitr/storage'
import { createTestApp } from 'kitr/testing'
import { afterEach, describe, expect, it } from 'vitest'

afterEach(() => onlineManager.setOnline(true))

describe('offline orders', () => {
  it('starts from the saved snapshot', async () => {
    const storage = createMemoryStorageDriver()
    const yesterday = new QueryClient()
    yesterday.setQueryData(['orders', 'list'], [{ id: 'ord_1042', customer: 'Ada', total: 129 }])
    createOffline(yesterday, { storage, buster: '1.4.0' }).persist()

    const app = await createTestApp({
      environment: 'client',
      providers: [queryProvider, offlineProvider],
      config: { offline: { storage, buster: '1.4.0' } },
    })

    expect(app.container.use('offline').restored).toBe(true)
    expect(app.container.use('queryClient').getQueryData(['orders', 'list'])).toEqual([
      { id: 'ord_1042', customer: 'Ada', total: 129 },
    ])
  })

  it('drops a snapshot from another version', async () => {
    const storage = createMemoryStorageDriver()
    const old = new QueryClient()
    old.setQueryData(['orders', 'list'], [])
    createOffline(old, { storage, buster: '1.4.0' }).persist()

    const app = await createTestApp({
      environment: 'client',
      providers: [queryProvider, offlineProvider],
      config: { offline: { storage, buster: '1.5.0' } },
    })

    expect(app.container.use('offline').restored).toBe(false)
    expect(storage.get('kitr:query-cache')).toBeNull()
  })

  it('reports offline state', async () => {
    const app = await createTestApp({
      environment: 'client',
      providers: [queryProvider, offlineProvider],
      config: { offline: { storage: createMemoryStorageDriver() } },
    })
    const offline = app.container.use('offline')

    onlineManager.setOnline(false)
    expect(offline.isOnline()).toBe(false)
    expect(offline.pendingMutations()).toBe(0)
  })
})
```

To test that a mutation queues, build it on the client with `client.getMutationCache().build(client, { mutationKey, mutationFn })`, call `execute()` while `onlineManager.setOnline(false)`, and wait for `offline.pendingMutations()` to be `1`. Paused mutations only resume on a mounted client: call `client.mount()` in the test, which `QueryClientProvider` does in the app.

## Extend

The snapshot goes through a `StorageDriver`, the same interface [Storage](/packages/storage) uses for its native stores (see [Write a storage driver](/packages/storage#write-a-storage-driver)). Pass your own as `storage` to keep the snapshot somewhere else. The usual reason is size: [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) holds far more than the 5 MB of `localStorage`.

The offline service reads the snapshot synchronously with `get()`, so an async store must be loaded into memory first. `createAsyncStorageDriver` from `kitr/storage` does that in its `hydrate()`. This driver uses [idb-keyval](https://github.com/jakearchibald/idb-keyval):

```ts
// app/lib/idb-snapshot.ts
import { createStore, del, get, set } from 'idb-keyval'
import { createAsyncStorageDriver } from 'kitr/storage'

const store = createStore('acme-offline', 'snapshots')

export const idbSnapshotStorage = createAsyncStorageDriver({
  name: 'idb:offline',
  load: async () => {
    const snapshot = await get<string>('kitr:query-cache', store)
    return snapshot ? { 'kitr:query-cache': snapshot } : {}
  },
  write: (key, raw) => set(key, raw, store),
  erase: (key) => del(key, store),
})
```

```ts
// config/offline.ts
import { defineConfig } from 'kitr/offline'
import { env } from '#app/env'
import { idbSnapshotStorage } from '#app/lib/idb-snapshot'

export default defineConfig({
  maxAge: 24 * 60 * 60 * 1000,
  buster: env.VITE_APP_VERSION,
  storage: idbSnapshotStorage,
})
```

Nothing calls `hydrate()` on a driver passed in config, so do it in a provider listed **before** `@kitr/offline/provider` in `kitrrc.ts`. Its `boot()` finishes before the offline provider restores:

```ts
// app/providers/idb-snapshot.ts
import { defineProvider } from 'kitr/app'
import { idbSnapshotStorage } from '#app/lib/idb-snapshot'

export default defineProvider({
  name: 'idb-snapshot',
  async boot(app) {
    if (app.isClient) await idbSnapshotStorage.hydrate?.()
  },
})
```

Writes go to IndexedDB in the background after each save. A failed write is logged as `[kitr/storage] idb:offline: <error>`; pass `onError` to `createAsyncStorageDriver` to handle it yourself.

## Devtools

`kitr/offline` has no panel. With [Devtools](/packages/devtools) installed it writes to the Log panel under `offline`: `restored` with the number of queries and mutations it loaded at boot, and `persist failed` with the error when a save is refused, usually because storage is full. The restored queries show in the [Query](/packages/query) panel like any others.

## Next steps

- [API reference](/packages/offline/api)
- [TanStack Query: network mode](https://tanstack.com/query/latest/docs/framework/react/guides/network-mode): how paused queries and mutations behave.
- [Query](/packages/query): the queries and mutations this package saves.
- [Storage](/packages/storage): where the snapshot lives, and native drivers on desktop and mobile.
- [Web](/packages/web): make the app installable so it opens with no connection.


# Platform API

Source: https://kitr.dev/packages/platform/api

Every export of `kitr/platform`, `kitr/platform/react`, `kitr/platform/provider`, `kitr/platform/devtools`, read from the published type definitions. The [guide](/packages/platform) shows them in use.

## kitr/platform

### createPlatform

```ts
function createPlatform(app: KitrApp, driver?: PlatformDriver): Platform;
```

Build the `platform` service from a driver (default: the registered one, else the browser/server default). The provider binds it for you.

### deepLinkPath

```ts
function deepLinkPath(url: string, prefixes?: string[]): string;
```

Strip a configured prefix from a deep link so it can be handed to the router.

### defaultDriver

```ts
function defaultDriver(): PlatformDriver;
```

The browser (or server) driver used when no platform package registered one.

### osFromUserAgent

```ts
function osFromUserAgent(ua: string): PlatformOs;
```

Map a user agent string to a `PlatformOs`; iPhone and iPad user agents are checked before macOS.

### perPlatform

```ts
function perPlatform<T>(platform: Pick<Platform, 'type' | 'os' | 'native'>, impls: Partial<Record<PlatformType | PlatformOs | 'native', () => T>> & {
  default: () => T;
}): T;
```

Pick an implementation per platform without branching in components:
```ts
const save = perPlatform(platform, { web: () => download, mobile: () => share, desktop: () => saveDialog })
```
Keys are platform types or OS names; `native` covers every native shell; `default` is required.

### defineConfig

```ts
const defineConfig: <const C extends PlatformConfig>(config: C) => C;
```

Typed helper for `config/platform.ts`.

### Platform

```ts
interface Platform {
  /** The active driver's platform type. */
  readonly type: PlatformType;
  /** True inside a native shell (Capacitor, Tauri, Electron). */
  readonly native: boolean;
  /** The operating system, read from the driver on every access. */
  readonly os: PlatformOs | string;
  /** Installed as an app: a standalone PWA or any native shell. */
  readonly standalone: boolean;
  /** The platform name from kitrrc.ts the bundle was built for, when known. */
  readonly name: string | undefined;
  /** The active driver, for anything the service does not wrap. */
  readonly driver: PlatformDriver;
  /** Whether the device reports a connection. */
  isOnline(): boolean;
  /** The native app version, or `'0.0.0'` where there is none. */
  appVersion(): Promise<string>;
  /** Foreground (`true`) and background (`false`) changes. Returns an unsubscribe function. */
  onAppState(listener: (active: boolean) => void): () => void;
  /** Hardware or window back button. Never fires where the driver has none. Returns an unsubscribe function. */
  onBackButton(listener: (info: {
    canGoBack: boolean;
  }) => void): () => void;
  /** URLs the OS opens in the running app. Returns an unsubscribe function. */
  onDeepLink(listener: (url: string) => void): () => void;
  /** Connection changes. Returns an unsubscribe function. */
  onOnline(listener: (online: boolean) => void): () => void;
  /** Safe-area insets in pixels. */
  safeArea(): SafeArea;
  /** Open a URL in the system browser (native) or a new tab (web). */
  openExternal(url: string): Promise<void>;
  /** Close the app where the driver supports it; resolves and does nothing elsewhere. */
  exit(): Promise<void>;
  /** `platform.is('mobile')`, `platform.is('ios')`: matches the type or the OS. */
  is(what: PlatformType | PlatformOs): boolean;
}
```

The `platform` service: the active driver plus safe defaults for everything it leaves out.

### PlatformConfig

```ts
interface PlatformConfig {
  /** Path prefixes (`'/open'`) to strip from deep links; pass them to `deepLinkPath()`. The scheme and host are always dropped. */
  deepLinkPrefixes?: string[];
}
```

The options in `config/platform.ts`.

### PlatformDriver

```ts
interface PlatformDriver {
  /** `web`, `mobile`, `desktop`, `server` or a custom platform type. */
  type: PlatformType;
  /** True inside a native shell (Capacitor, Tauri, Electron). */
  native: boolean;
  /** The operating system, read on every access. */
  os(): PlatformOs | string;
  /** Installed as an app (PWA standalone, native shell). */
  standalone?(): boolean;
  /** The native app version. Default `'0.0.0'`. */
  appVersion?(): Promise<string>;
  /** Foreground/background. */
  onAppState?(listener: (active: boolean) => void): () => void;
  /** Hardware or window back button. */
  onBackButton?(listener: (info: {
    canGoBack: boolean;
  }) => void): () => void;
  /** Deep links and custom-scheme URLs opened while the app runs. */
  onDeepLink?(listener: (url: string) => void): () => void;
  /** Connection changes. Default: the browser's `online` and `offline` events. */
  onOnline?(listener: (online: boolean) => void): () => void;
  /** Whether the device has a connection. Default: `navigator.onLine`. */
  isOnline?(): boolean;
  /** Safe-area insets. Default: the CSS `env(safe-area-inset-*)` values. */
  safeArea?(): SafeArea;
  /** Open a URL in the system browser (native) or a new tab (web). */
  openExternal?(url: string): Promise<void>;
  /** Exit the app where the platform allows it (Android back at root, desktop). */
  exit?(): Promise<void>;
}
```

What a platform package implements so `kitr/platform` can answer for it. Register one with
`app.drivers.register('platform', driver)`; every optional member falls back to a browser default.

### SafeArea

```ts
interface SafeArea {
  /** Inset from the top edge (status bar, notch). */
  top: number;
  /** Inset from the right edge (notch in landscape). */
  right: number;
  /** Inset from the bottom edge (home indicator). */
  bottom: number;
  /** Inset from the left edge (notch in landscape). */
  left: number;
}
```

Safe-area insets in CSS pixels: the space the notch, status bar and home indicator cover.

### PlatformOs

```ts
type PlatformOs = 'ios' | 'android' | 'macos' | 'windows' | 'linux' | 'server' | 'unknown';
```

The operating system a driver reports; `server` during server rendering, `unknown` when the user agent matches none.

### PlatformType

```ts
/** The kind of place the app runs: `web`, `mobile`, `desktop`, `server`, or a custom platform's own type. */
type PlatformType = 'web' | 'mobile' | 'desktop' | 'server' | (string & {});
```

The kind of place the app runs: `web`, `mobile`, `desktop`, `server`, or a custom platform's own type.

## kitr/platform/react

### useAppState

```ts
function useAppState(): boolean;
```

Foreground (`true`) or background. Backed by Capacitor App on mobile, window focus on desktop, visibility on the web.

### useBackButton

```ts
function useBackButton(handler: (info: {
  canGoBack: boolean;
}) => void): void;
```

Android hardware back button, desktop window close. Return nothing to let the default run.

### useDeepLink

```ts
function useDeepLink(handler: (url: string) => void): void;
```

Deep links opened while the app runs. Pair with `deepLinkPath()` to hand them to the router.

### useOnline

```ts
function useOnline(): boolean;
```

`true` while the device reports a connection. Hydration-safe: the server and first render say online.

### usePlatform

```ts
function usePlatform(): Platform;
```

The `platform` service from the container.

### useSafeArea

```ts
function useSafeArea(): SafeArea;
```

Safe-area insets (notch, home indicator). Zero on the server and first render.

## kitr/platform/provider

### platformProvider

```ts
const platformProvider: import("@kitr/core").KitrProvider;
```

Binds the `platform` service from the active platform driver. Platform packages
(`kitr/mobile/provider`, `kitr/desktop/provider`...) register their driver in `register()`,
so list them before this provider in kitrrc.ts; `kitr add` keeps that order.

## kitr/platform/devtools

### panels

```ts
function panels(app: KitrApp): DevtoolsPanel[];
```

The Platform panel: active platform, OS and which package supplies each capability driver.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Platform

Source: https://kitr.dev/packages/platform

An app that ships to the browser, a phone and a desktop window keeps asking the same questions: where am I running, am I online, did the user press back, which link opened me, how big is the notch. `kitr/platform` answers them once, with one `platform` service and a set of React hooks, so components never sniff user agents or check for `window.Capacitor`.

It is built on the kitr driver registry: each platform package registers a `PlatformDriver` for the place it runs, and `kitr/platform` wraps whichever one is active, filling every gap with a browser default. [Web](/packages/web) registers the browser driver, [Mobile](/packages/mobile) the Capacitor driver and [Desktop](/packages/desktop) the Tauri and Electron drivers.

It runs on both sides. In the browser and in native shells it reports the real device; during server rendering it returns safe defaults (online, in the foreground, no insets), so the first render matches the HTML. For device features such as the camera, biometrics or haptics, use [Native](/packages/native) instead.

The examples on this page follow the Acme orders app at `app.acme.com`, which runs in the browser, as an installed PWA and in the Capacitor shell Ada's field team uses on their phones.

## Install

```sh
kitr add platform
```

What `kitr add platform` does:

- Installs `@kitr/platform`.
- Runs the [React](/packages/react) recipe first if it is missing.
- Adds `() => import('@kitr/platform/provider')` to `providers` in `kitrrc.ts`.
- Adds `@kitr/platform` to `packages` in `kitrrc.ts`.
- Writes `config/platform.ts` (shown under Configure) and regenerates `config/index.ts`.
- Adds a `kitr: platform` section to `AGENTS.md`: use the hooks from `kitr/platform/react` instead of user agents or `window.__TAURI__`, and `platform.is()` to match a type or an OS.

`kitr add platform` asks no questions and adds no env variables.

You rarely run it by hand. `kitr add mobile` and `kitr add desktop` add it for you, because both platforms need it, and the `mobile` and `desktop` kits include it.

`kitr remove platform` reverses every step above: it removes the provider, the `packages` entry, the dependency, the `AGENTS.md` section and `config/platform.ts`, then lists the files that still import `kitr/platform`.

## Configure

`kitr add platform` writes this file:

```ts
// config/platform.ts
import { defineConfig } from 'kitr/platform'

export default defineConfig({
  // Deep links are routed after stripping these prefixes.
  deepLinkPrefixes: [],
})
```

| Option | Default | Description |
| --- | --- | --- |
| `deepLinkPrefixes` | `[]` | Path prefixes to strip from deep links before routing, such as `'/open'` for `acme://open/orders/1042`. The scheme and host are always dropped first. Pass them to `deepLinkPath()`, as shown in "Route deep links". |

The provider does not read `deepLinkPrefixes` on its own. Read it with `useConfig('platform')` and hand it to `deepLinkPath()` where you route links.

The `platform` service has no other options. Which driver it wraps depends on the platform providers listed in `kitrrc.ts`:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { mobile } from 'kitr/mobile'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/platform', '@kitr/storage', '@kitr/web', '@kitr/mobile'],
  providers: [
    () => import('@kitr/mobile/provider'),
    () => import('@kitr/web/provider'),
    () => import('@kitr/platform/provider'),
    () => import('@kitr/storage/provider'),
  ],
  platforms: {
    site: web({ mode: 'spa', pwa: true }),
    phone: mobile({ appId: 'com.acme.orders' }),
  },
})
```

The `platform` service is created the first time something reads it, after every provider has registered, so the place of `@kitr/platform/provider` in the list does not matter. The highest-priority driver wins (see "How the driver is chosen").

## Show where the app runs

`usePlatform()` returns the `platform` service. Render it to see what kitr detected:

```tsx
// app/components/platform-badge.tsx
import { usePlatform } from 'kitr/platform/react'

export function PlatformBadge() {
  const platform = usePlatform()
  return (
    <span>
      {platform.type} · {platform.os}
      {platform.native ? ' · native' : ''}
    </span>
  )
}
```

Put `<PlatformBadge />` in a page and run `kitr dev site`. On a Mac in Chrome it shows `web · macos`. In the iOS simulator through `kitr dev phone` it shows `mobile · ios · native`.

## Read the platform outside React

The service lives in the app container, so loaders, stores and plain modules read the same object:

```ts
// app/features/orders/receipt.ts
import { app } from '#app/app'

export function receiptFileName(orderId: string) {
  const platform = app.container.use('platform')
  return platform.is('windows') ? `Acme ${orderId}.pdf` : `acme-${orderId}.pdf`
}
// receiptFileName('ord_1042') on macOS => 'acme-ord_1042.pdf'
```

Read it after `app.boot()`. Before boot, or in an app without `@kitr/platform/provider`, `use('platform')` throws `[kitr] No binding named "platform". Did you add the package that provides it?`.

## What the platform service knows

| Member | Type | Description |
| --- | --- | --- |
| `type` | `'web' \| 'mobile' \| 'desktop' \| 'server' \| string` | The kind of platform the driver belongs to. |
| `os` | `'ios' \| 'android' \| 'macos' \| 'windows' \| 'linux' \| 'server' \| 'unknown'` | The operating system. Read each time you access it. |
| `native` | `boolean` | `true` inside a native shell (Capacitor, Tauri, Electron). |
| `standalone` | `boolean` | `true` when installed: a PWA in standalone display mode, or any native shell. |
| `name` | `string \| undefined` | The platform name from `kitrrc.ts` this bundle was built for, such as `'site'` or `'phone'`. |
| `driver` | `PlatformDriver` | The active driver, for anything the service does not wrap. |
| `is(what)` | `boolean` | `true` when `what` equals the type or the OS. |
| `isOnline()` | `boolean` | Whether the device reports a connection. |
| `appVersion()` | `Promise<string>` | The native app version, or `'0.0.0'` where there is none. |
| `onAppState(fn)` | unsubscribe | Foreground (`true`) and background (`false`). |
| `onBackButton(fn)` | unsubscribe | Hardware or window back button, with `{ canGoBack }`. |
| `onDeepLink(fn)` | unsubscribe | URLs opened while the app runs. |
| `onOnline(fn)` | unsubscribe | Connection changes. |
| `safeArea()` | `{ top, right, bottom, left }` | Safe-area insets in pixels. |
| `openExternal(url)` | `Promise<void>` | Opens a URL in the system browser, or a new tab on the web. |
| `exit()` | `Promise<void>` | Closes the app where the platform allows it. |

## Subscribe to changes outside React

Every `on*` method returns a function that removes the listener. Use them in stores, sync engines and anything else that lives outside a component:

```ts
// app/features/orders/order-sync.ts
import { app } from '#app/app'

export function startOrderSync(flush: () => Promise<void>) {
  const platform = app.container.use('platform')
  const stopOnline = platform.onOnline((online) => {
    if (online) void flush()
  })
  const stopAppState = platform.onAppState((active) => {
    if (active) void flush()
  })
  return () => {
    stopOnline()
    stopAppState()
  }
}
```

```ts
// app/features/orders/start.ts
import { startOrderSync } from './order-sync'

const stop = startOrderSync(async () => {
  // ...send queued orders
})

// later, on sign-out
stop()
```

The listeners fire with the new value only; read the current one with `platform.isOnline()` when you start.

## Check whether the app is installed

`platform.standalone` is `true` when the app runs installed: a PWA opened from the home screen, or any native shell. Use it to hide install prompts and "open in app" banners:

```tsx
// app/components/open-in-app.tsx
import { usePlatform } from 'kitr/platform/react'

export function OpenInApp() {
  const platform = usePlatform()
  const phone = platform.is('ios') || platform.is('android')
  if (platform.standalone || !phone) return null
  return <a href="acme://orders">Open in the Acme app</a>
}
```

In the browser, the web driver reads the `(display-mode: standalone)` media query and Safari's `navigator.standalone`.

## Match a platform or an OS

`platform.is()` takes a type or an OS, so one call covers both questions:

```ts
// app/features/orders/print.ts
import { app } from '#app/app'

const platform = app.container.use('platform')

platform.is('mobile') // => true in the Capacitor shell
platform.is('ios') // => true on an iPhone, in the shell or in Safari
platform.is('desktop') // => false in the browser
```

Don't read `navigator.userAgent` or `window.Capacitor` in components. The driver already knows, and tests can replace it (see Testing).

## Pick an implementation per platform

When the same action works differently in each place, `perPlatform()` picks the implementation without an `if` chain. Keys are OS names, platform types or `native`; `default` is required:

```ts
// app/features/invoices/save-invoice.ts
import { app } from '#app/app'
import { perPlatform } from 'kitr/platform'

export function saveInvoice(invoiceId: string) {
  const platform = app.container.use('platform')
  return perPlatform(platform, {
    ios: () => `share ${invoiceId}`,
    desktop: () => `save dialog for ${invoiceId}`,
    native: () => `write ${invoiceId} to the documents folder`,
    default: () => `download ${invoiceId}`,
  })
}
```

The most specific key wins: the OS first, then the type, then `native`, then `default`.

| Running on | Result |
| --- | --- |
| iPhone, Capacitor shell | `'share inv_7'` (the `ios` key) |
| Android, Capacitor shell | `'write inv_7 to the documents folder'` (`native`) |
| Windows, Electron | `'save dialog for inv_7'` (`desktop`) |
| Chrome on macOS | `'download inv_7'` (`default`) |

`perPlatform()` takes anything with `type`, `os` and `native`, so you can pass a plain object in tests.

## Show an offline banner

`useOnline()` is `true` while the device reports a connection, and re-renders when it changes:

```tsx
// app/components/offline-banner.tsx
import { useOnline } from 'kitr/platform/react'

export function OfflineBanner() {
  const online = useOnline()
  if (online) return null
  return <div role="status">You are offline. New orders will sync when you reconnect.</div>
}
```

The hook is hydration-safe: the server and the first client render say online, and the real value follows. In the browser it follows the `online` and `offline` events. For queued writes and a query cache that pauses offline, add [Offline](/packages/offline).

## Pause work in the background

`useAppState()` is `true` in the foreground. In the browser it follows page visibility; inside Capacitor it follows the app state; the desktop drivers follow window focus:

```tsx
// app/features/orders/live-orders.tsx
import { useAppState } from 'kitr/platform/react'
import { useEffect } from 'react'

export function LiveOrders({ poll }: { poll: () => void }) {
  const active = useAppState()
  useEffect(() => {
    if (!active) return
    const timer = setInterval(poll, 10_000)
    return () => clearInterval(timer)
  }, [active, poll])
  return <p>{active ? 'Live' : 'Paused'}</p>
}
```

It starts as `true`, so the server render and the first client render agree.

## Handle the back button

`useBackButton()` receives the Android hardware back button, and on desktop whatever the desktop driver reports (the window closing). The handler gets `{ canGoBack }`:

```tsx
// app/components/order-sheet.tsx
import { useBackButton, usePlatform } from 'kitr/platform/react'
import { useCallback } from 'react'

export function OrderSheet({ open, onClose }: { open: boolean; onClose: () => void }) {
  const platform = usePlatform()
  useBackButton(
    useCallback(
      ({ canGoBack }) => {
        if (open) onClose()
        else if (canGoBack) window.history.back()
        else void platform.exit()
      },
      [open, onClose, platform],
    ),
  )
  return open ? <aside>Order ord_1042</aside> : null
}
```

Wrap the handler in `useCallback`: the hook subscribes again whenever the function changes. On Android, Capacitor stops its default back behaviour while any listener is registered, so the handler must go back or exit itself. The browser driver has no back button, so the handler never runs on the web.

## Route deep links

`useDeepLink()` receives URLs the OS hands the app while it runs: custom schemes (`acme://orders/1042`) and app links (`https://app.acme.com/orders/1042`). `deepLinkPath()` turns them into a router path:

```tsx
// app/components/deep-links.tsx
import { useNavigate } from '@tanstack/react-router'
import { useConfig } from 'kitr/react'
import { deepLinkPath } from 'kitr/platform'
import { useDeepLink } from 'kitr/platform/react'
import { useCallback } from 'react'

export function DeepLinks() {
  const navigate = useNavigate()
  const { deepLinkPrefixes } = useConfig('platform')
  useDeepLink(
    useCallback(
      (url) => void navigate({ to: deepLinkPath(url, deepLinkPrefixes) }),
      [navigate, deepLinkPrefixes],
    ),
  )
  return null
}
```

Render `<DeepLinks />` once in the root route. `deepLinkPath()` drops the scheme and host, keeps the query and hash, then strips the first prefix that matches:

```ts
// app/features/links.ts
import { deepLinkPath } from 'kitr/platform'

deepLinkPath('acme://orders/1042') // => '/orders/1042'
deepLinkPath('https://app.acme.com/orders/1042?tab=invoices#notes') // => '/orders/1042?tab=invoices#notes'
deepLinkPath('acme://open/orders/7', ['/open']) // => '/orders/7'
deepLinkPath('https://acme.com/app/projects/3', ['/app']) // => '/projects/3'
deepLinkPath('orders/3') // => '/orders/3'
```

For a custom scheme, the part after `://` up to the next `/` is the URL's host, so `acme://orders/1042` becomes `/orders/1042`, not `/1042`. Prefixes are paths: `'https://app.acme.com'` as a prefix never matches, and it is not needed because the host is always dropped. Registering the scheme in the native projects is the platform's job; see [Mobile](/packages/mobile).

## Respect the notch and home indicator

`useSafeArea()` returns the safe-area insets in pixels, read from the CSS `env(safe-area-inset-*)` values:

```tsx
// app/components/tab-bar.tsx
import { useSafeArea } from 'kitr/platform/react'

export function TabBar() {
  const insets = useSafeArea()
  return <nav style={{ paddingBottom: 8 + insets.bottom }}>Orders · Invoices · Projects</nav>
}
```

The insets are `{ top: 0, right: 0, bottom: 0, left: 0 }` on the server and the first render, then update on mount and on every window resize. iOS reports non-zero values only when the viewport meta has `viewport-fit=cover`. For layout alone, CSS can use `env(safe-area-inset-bottom)` directly; the hook is for values you compute in JavaScript.

## Open links outside the app

Inside a native shell a plain link replaces the app's own page. `platform.openExternal()` opens the system browser there, and a new tab (`noopener`) on the web:

```tsx
// app/components/status-link.tsx
import { usePlatform } from 'kitr/platform/react'

export function StatusLink() {
  const platform = usePlatform()
  return (
    <button type="button" onClick={() => void platform.openExternal('https://status.acme.com')}>
      Service status
    </button>
  )
}
```

## Read the app version

`platform.appVersion()` resolves to the version of the native app, from the driver. Where there is none, such as the browser, it resolves to `'0.0.0'`:

```ts
// app/features/support/report.ts
import { app } from '#app/app'

export async function supportReport() {
  const platform = app.container.use('platform')
  return `${platform.type}/${platform.os} ${await platform.appVersion()}`
}
// in Chrome on macOS => 'web/macos 0.0.0'
```

## Exit the app

`platform.exit()` closes the app where the driver supports it: Android at the root of the back stack, and the desktop shells. In the browser it resolves and does nothing. Apple discourages apps that quit themselves, so don't offer it on iOS:

```ts
// app/features/session/sign-out.ts
import { app } from '#app/app'

export async function signOutAndExit() {
  // ...
  await app.container.use('platform').exit()
}
```

## Know which build is running

`platform.name` is the platform name from `kitrrc.ts` the bundle was built for. One codebase with `site` and `phone` platforms can tell them apart at run time:

```tsx
// app/components/store-badge.tsx
import { usePlatform } from 'kitr/platform/react'

export function StoreBadge() {
  const platform = usePlatform()
  if (platform.name === 'phone') return null
  return <a href="https://apps.apple.com/app/acme-orders">Get the iPhone app</a>
}
```

`kitr dev` and `kitr build` set it from `KITR_PLATFORM`, through `import.meta.env.KITR_PLATFORM`. To drop code from a bundle entirely, compare `import.meta.env.KITR_PLATFORM` itself so the bundler can remove the dead branch; see [Web](/packages/web).

## Render on the server

During server rendering there is no `window`, so the default driver reports type `server`, OS `server`, online, and zero insets. With `kitr/web/provider` registered, the type is `web` and the OS is still `server`. Every hook starts from a value the server can produce:

| Hook | Server and first render |
| --- | --- |
| `useOnline()` | `true` |
| `useAppState()` | `true` |
| `useSafeArea()` | `{ top: 0, right: 0, bottom: 0, left: 0 }` |
| `usePlatform()` | The service; `os` is `'server'` on the server. |

Branch on `platform.os` only after mount (in an effect or event handler) when the server and the client could disagree, or the first render will not match the HTML.

## How the driver is chosen

Platform providers register a driver for the `platform` capability. The registry keeps the one with the highest priority:

| Provider | Registers when | Type | Priority |
| --- | --- | --- | --- |
| `kitr/web/provider` | always | `web` | 0 |
| `kitr/mobile/provider` | inside Capacitor | `mobile` | 10 |
| `kitr/desktop/provider` | inside Tauri or Electron | `desktop` | 10 |
| none | no driver registered | `web` in a browser, `server` without `window` | |

So the same bundle answers `web` in a browser and `mobile` in the iOS shell. A driver may leave methods out; the service fills them in:

| Method | When the driver leaves it out |
| --- | --- |
| `isOnline()`, `onOnline()` | `navigator.onLine` and the `online`/`offline` events. |
| `onAppState()` | `document.visibilityState`. |
| `safeArea()` | The CSS `env(safe-area-inset-*)` values. |
| `openExternal()` | `window.open(url, '_blank', 'noopener')`. |
| `onBackButton()`, `onDeepLink()` | Never fire. |
| `appVersion()` | `'0.0.0'`. |
| `exit()` | Does nothing. |
| `standalone` | The driver's `native` value. |

## Devtools

With [Devtools](/packages/devtools) installed, the provider adds a Platform panel and logs one line at boot, such as `running as mobile (ios), native`. The panel shows:

- the platform `name`, `type`, `os`, `native`, `standalone` and `online` values;
- every capability with a registered driver (`platform`, `storage` and others) and who supplied it, such as `mobile (priority 10)`. In a plain browser it reads "No platform drivers registered (browser defaults)" until a provider registers one.

## Errors

| Message | When | What to do |
| --- | --- | --- |
| `[kitr] No binding named "platform". Did you add the package that provides it?` | `use('platform')` in an app without `@kitr/platform/provider`, or before boot. | `kitr add platform`, or read it after `app.boot()`. |
| `[kitr/react] useApp() must be used inside <KitrProvider>.` | A hook from `kitr/platform/react` rendered outside the kitr provider tree. | Render inside `KitrProvider`, or use `renderWithKitr` in tests. |
| `[kitr] Missing config "platform". Create config/platform.ts or pass it to createApp().` | `useConfig('platform')` without `config/platform.ts`. | Run `kitr add platform`, or read it with `useApp().config.get('platform', { deepLinkPrefixes: [] })`. |

## Testing

Tests replace the driver. Register a fake one from a small provider, then render with `renderWithKitr` from [Testing](/packages/testing). Your components never know the difference:

```tsx
// test/order-sheet.test.tsx
import { act, screen } from '@testing-library/react'
import { defineProvider } from 'kitr/app'
import type { PlatformDriver } from 'kitr/platform'
import { platformProvider } from 'kitr/platform/provider'
import { usePlatform, useBackButton } from 'kitr/platform/react'
import { createTestApp, renderWithKitr } from 'kitr/testing/react'
import { useCallback, useState } from 'react'
import { describe, expect, it } from 'vitest'

function fakeAndroid() {
  const backListeners = new Set<(info: { canGoBack: boolean }) => void>()
  const driver: PlatformDriver = {
    type: 'mobile',
    native: true,
    os: () => 'android',
    onBackButton(listener) {
      backListeners.add(listener)
      return () => backListeners.delete(listener)
    },
  }
  const provider = defineProvider({
    name: 'fake-android',
    register(app) {
      app.drivers.register('platform', driver)
    },
  })
  const pressBack = () => {
    for (const listener of backListeners) listener({ canGoBack: false })
  }
  return { provider, pressBack }
}

function OrderSheet() {
  const platform = usePlatform()
  const [open, setOpen] = useState(true)
  useBackButton(useCallback(() => setOpen(false), []))
  return (
    <div>
      <p>{platform.is('android') ? 'Android' : 'Other'}</p>
      {open ? <aside>Order ord_1042 for Ada</aside> : <p>Sheet closed</p>}
    </div>
  )
}

describe('OrderSheet on Android', () => {
  it('closes the sheet on the hardware back button', async () => {
    const android = fakeAndroid()
    const app = await createTestApp({ providers: [android.provider, platformProvider] })
    renderWithKitr(<OrderSheet />, { app })

    expect(screen.getByText('Android')).toBeTruthy()
    expect(screen.getByText('Order ord_1042 for Ada')).toBeTruthy()

    act(() => android.pressBack())
    expect(await screen.findByText('Sheet closed')).toBeTruthy()
  })
})
```

The driver above leaves out everything the test does not need; the service fills the rest with browser defaults. Pure helpers need no app at all:

```ts
// test/save-invoice.test.ts
import { perPlatform } from 'kitr/platform'
import { describe, expect, it } from 'vitest'

const impls = {
  ios: () => 'share',
  desktop: () => 'save dialog',
  native: () => 'documents folder',
  default: () => 'download',
}

describe('saving an invoice', () => {
  it('picks the most specific implementation', () => {
    expect(perPlatform({ type: 'mobile', os: 'ios', native: true }, impls)).toBe('share')
    expect(perPlatform({ type: 'mobile', os: 'android', native: true }, impls)).toBe('documents folder')
    expect(perPlatform({ type: 'desktop', os: 'windows', native: true }, impls)).toBe('save dialog')
    expect(perPlatform({ type: 'web', os: 'macos', native: false }, impls)).toBe('download')
  })
})
```

## Extend

A new place to run (a kiosk browser, a TV, a browser extension) gets its own driver. Implement `PlatformDriver` and register it from a provider. Only `type`, `native` and `os` are required:

```ts
// app/providers/kiosk-platform.ts
import { defineProvider } from 'kitr/app'
import type { PlatformDriver } from 'kitr/platform'

/** The order-pickup kiosks in Acme warehouses run the web build in a locked-down browser. */
function kioskDriver(): PlatformDriver {
  return {
    type: 'kiosk',
    native: false,
    os: () => 'linux',
    standalone: () => true,
    appVersion: async () => '2.3.0',
    onBackButton(listener) {
      const onKey = (event: KeyboardEvent) => {
        if (event.key === 'Escape') listener({ canGoBack: window.history.length > 1 })
      }
      window.addEventListener('keydown', onKey)
      return () => window.removeEventListener('keydown', onKey)
    },
    // The kiosk never leaves the app.
    openExternal: async () => {},
  }
}

export default defineProvider({
  name: 'kiosk-platform',
  register(app) {
    if (typeof navigator === 'undefined' || !navigator.userAgent.includes('AcmeKiosk')) return
    app.drivers.register('platform', kioskDriver(), { platform: 'kiosk', priority: 20 })
  },
})
```

List it in `kitrrc.ts` next to the other providers:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/platform', '@kitr/web'],
  providers: [
    () => import('@kitr/web/provider'),
    () => import('./app/providers/kiosk-platform'),
    () => import('@kitr/platform/provider'),
  ],
  platforms: {
    site: web({ mode: 'spa' }),
  },
})
```

On a kiosk, `platform.is('kiosk')` is `true`, `perPlatform(platform, { kiosk: () => ..., default: () => ... })` picks the kiosk branch, and the devtools panel lists the driver as `kiosk (priority 20)`. Priority 20 beats the web driver (0) and the native drivers (10). Register only when you are sure you run there, as above, because the highest priority wins everywhere. See [`PlatformDriver`](/packages/platform/api) for every member.

To make the kiosk a platform that `kitr dev` and `kitr build` can run, write a platform package with `definePlatform()`; [Platforms](/docs/platforms) shows one.

## Next steps

- [API reference](/packages/platform/api)
- [Web](/packages/web): the browser driver and installable apps
- [Mobile](/packages/mobile): the Capacitor driver, deep link registration and native storage
- [Desktop](/packages/desktop): the desktop shells
- [Offline](/packages/offline): queued writes and a cache that pauses without a connection
- [Platforms](/docs/platforms): every platform type and the commands they share


# Query API

Source: https://kitr.dev/packages/query/api

`kitr/query` re-exports everything from `@tanstack/react-query` and adds the following.

## defineQuery

```ts
function defineQuery<TInput = void, TOutput = unknown>(contract: {
  key: (input: TInput) => QueryKey
  fetch: (input: TInput, ctx: { signal?: AbortSignal }) => Promise<TOutput>
  staleTime?: number
  source?: string
}): QueryDefinition<TInput, TOutput>
```

| Member | Description |
| --- | --- |
| `options(input)` | TanStack `queryOptions` for `useQuery`, `useSuspenseQuery`, `ensureQueryData`. Errors are normalised to `KitrError`. |
| `key(input)` | The cache key. |
| `fetch(input, signal?)` | Call the source directly, bypassing the cache. |
| `contract` | The full contract, for tooling. |

## defineMutation

```ts
function defineMutation<TInput = void, TOutput = unknown>(contract: {
  mutate: (input: TInput) => Promise<TOutput>
  effects?: CacheEffect | ((result: TOutput, input: TInput) => CacheEffect)
  source?: string
}): MutationDefinition<TInput, TOutput>
```

| Member | Description |
| --- | --- |
| `options({ queryClient })` | TanStack mutation options that apply `effects` on success. |
| `mutate(input)` | Call the source directly, without effects. |
| `effectsFor(result, input)` | The effects for one result. |

## useKitrMutation

```ts
function useKitrMutation<TInput, TOutput>(
  definition: MutationDefinition<TInput, TOutput>,
  overrides?: Omit<UseMutationOptions<TOutput, Error, TInput>, 'mutationFn'>,
): UseMutationResult<TOutput, Error, TInput>
```

`useMutation` with effects applied to the active `QueryClient`. Your own `onSuccess` runs after the effects.

## defineSubscription and useSubscription

```ts
function defineSubscription<TInput = void, TEvent = unknown>(contract: {
  key: (input: TInput) => QueryKey
  subscribe: (input: TInput, handlers: { next(event: TEvent): void; error?(e: KitrErrorShape): void }) => () => void
  effects?: (event: TEvent, input: TInput) => CacheEffect | void
}): SubscriptionDefinition<TInput, TEvent>

function useSubscription<TInput, TEvent>(
  definition: SubscriptionDefinition<TInput, TEvent>,
  input: TInput,
  options?: { enabled?: boolean; onEvent?: (event: TEvent) => void; onError?: (error: KitrErrorShape) => void },
): { status: 'idle' | 'open' | 'error'; lastEvent?: TEvent; error?: KitrErrorShape }
```

## CacheEffect

```ts
interface CacheEffect {
  invalidate?: QueryKey[]                       // prefix match
  set?: Array<{ key: QueryKey; data: unknown }> // write without refetching
  remove?: QueryKey[]
}
```

## applyCacheEffect and invalidate

```ts
applyCacheEffect(queryClient, effect): Promise<void>
invalidate(queryClient, ...keys): Promise<void[]>
```

For applying effects outside a mutation, such as in a test or a custom event handler.

## createQueryClient and defineConfig

```ts
createQueryClient(config?: QueryConfig): QueryClient
defineConfig(config: QueryConfig): QueryConfig
```

The provider calls `createQueryClient` with `config/query.ts` and binds it as `queryClient` in the container and in router context.


# Query

Source: https://kitr.dev/packages/query

Most screens show data that lives on a server: Acme's list of orders, one invoice, the projects a team owns. `kitr/query` loads that data, keeps a cached copy so going back to a page is instant, and refreshes it when it changes, whether because you saved something, another tab did, or a live update arrived.

It is [TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview), re-exported unchanged, plus a small **data contract**: you describe each piece of data once with `defineQuery`, `defineMutation` and `defineSubscription`, and every source (a REST API, your own API routes, server actions, realtime channels) plugs into it the same way. Every failure from every source arrives as one error type, `KitrError`.

It runs in the browser, and on the server while a page renders. For values only the browser owns, such as a cart or a sidebar toggle, use [State](/packages/state) instead.

This guide follows Acme's order screen from the first query to live updates and tests.

## When to use it

Use queries for **server data**: anything a server owns and the browser only displays or changes. Orders, invoices, the signed-in user's profile and a team's projects are all server data. The cache knows when they are stale and refetches them for you.

Use [State](/packages/state) for **client state**: values that exist only in the browser, such as a half-filled cart, a selected tab or a theme choice. Copying server data into a store means you now own keeping it fresh, which is the job this package already does.

## Install

```sh
kitr add query
```

What `kitr add` does:

- Installs `@kitr/query` and `@tanstack/react-query`, and `@tanstack/react-query-devtools` as a dev dependency.
- Adds `() => import('@kitr/query/provider')` to `providers` in `kitrrc.ts`.
- Adds `@kitr/query` to `packages` in `kitrrc.ts`.
- Writes `config/query.ts` (shown under [Configure](#configure)).
- Adds a `## kitr: query` section to `AGENTS.md` with four rules: import from `kitr/query`, keep each feature's queries in `app/features/<name>/queries.ts`, load data in route loaders with `ensureQueryData`, and declare cache `effects` on mutations instead of calling `invalidateQueries` in components.

`kitr add query` asks no questions. Every kit includes it: `blank` adds it directly, and every kit with [HTTP](/packages/http) gets it because `http` requires `query`. To see the changes without writing them, run it with `--dry-run`:

```sh
kitr add query --dry-run
```

`kitr remove query` reverses every step above and deletes `config/query.ts`. It then lists the files that still import `kitr/query`, which you remove by hand.

## Configure

`kitr add query` writes this file:

```ts
// config/query.ts
import { defineConfig } from 'kitr/query'

export default defineConfig({
  // Navigating back within 30s never refetches.
  staleTime: 30_000,
})
```

| Option | Default | Description |
| --- | --- | --- |
| `staleTime` | `30_000` | How long data counts as fresh, in milliseconds. Fresh data is served from the cache without a request. |
| `defaultOptions` | `{}` | Passed to `new QueryClient({ defaultOptions })`. Keys under `defaultOptions.queries` win over `staleTime` and the retry rule. |
| `defaultOptions.queries.retry` | no retry on 4xx, two retries otherwise | When a failed query retries. kitr's rule reads `error.status`: a status from 400 to 499 never retries; anything else retries up to twice. |
| `createClient` | | A function that returns your own `QueryClient`. When set, every other option is ignored. |

`kitr/query` adds no environment variables.

The provider reads this file at boot, builds the client with `createQueryClient(config)`, binds it in the container as `queryClient`, wraps the React tree in `QueryClientProvider` and hands the same client to the router as `context.queryClient`.

To change the defaults for every query, for example to stop refetching when the window regains focus, pass TanStack's own options:

```ts
// config/query.ts
import { defineConfig } from 'kitr/query'

export default defineConfig({
  staleTime: 60_000,
  defaultOptions: {
    queries: { refetchOnWindowFocus: false },
    mutations: { retry: 0 },
  },
})
```

To build the client yourself, for example to share one with code outside kitr, return it from `createClient`:

```ts
// config/query.ts
import { defineConfig, QueryClient } from 'kitr/query'

export default defineConfig({
  createClient: () =>
    new QueryClient({ defaultOptions: { queries: { staleTime: 10_000, retry: 1 } } }),
})
```

## Show your first query

A query needs two things: a **key**, its name in the cache, and a **fetch** function that loads it. Put both in the feature's `queries.ts`. This one returns fixed data so it runs in a fresh `kitr new` project; the next sections swap in real sources.

```ts
// app/features/orders/queries.ts
import { createKeys } from 'kitr/app'
import { defineQuery } from 'kitr/query'

export interface Order {
  id: string
  customer: string
  total: number
  status: 'open' | 'paid' | 'shipped'
}

export const orderKeys = createKeys('orders')

export const ordersQuery = defineQuery({
  key: () => orderKeys.list(),
  fetch: async (): Promise<Order[]> => [
    { id: 'ord_1', customer: 'Ada', total: 120, status: 'paid' },
    { id: 'ord_2', customer: 'Grace', total: 80, status: 'open' },
  ],
})
```

Then read it in a page:

```tsx
// app/routes/orders.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useQuery } from 'kitr/query'
import { ordersQuery } from '#app/features/orders/queries'

export const Route = createFileRoute('/orders')({
  component: OrdersPage,
})

function OrdersPage() {
  const { data: orders, isPending } = useQuery(ordersQuery.options())
  if (isPending) return <p>Loading orders…</p>
  return (
    <ul>
      {orders?.map((order) => (
        <li key={order.id}>
          {order.customer}: ${order.total} ({order.status})
        </li>
      ))}
    </ul>
  )
}
```

Open `/orders` and you see two lines, `Ada: $120 (paid)` and `Grace: $80 (open)`. Leave the page and come back within 30 seconds: the list shows at once, with no loading state, because it comes from the cache.

`ordersQuery.options()` returns ordinary TanStack [`queryOptions`](https://tanstack.com/query/latest/docs/framework/react/reference/queryOptions). Anything that takes query options takes it: `useQuery`, `useSuspenseQuery`, `useQueries`, `queryClient.fetchQuery`, `prefetchQuery` and `ensureQueryData`.

## Name cache entries with keys

A key is an array that names a piece of data in the cache. Two calls with equal keys share one cache entry and one request. `createKeys` from `kitr/app` builds keys in one shape for each resource, so every part of the app agrees on what to refresh:

```ts
// app/features/orders/keys.ts
import { createKeys } from 'kitr/app'

export const orderKeys = createKeys('orders')

orderKeys.all // => ['orders']
orderKeys.lists() // => ['orders', 'list']
orderKeys.list() // => ['orders', 'list']
orderKeys.list({ status: 'open' }) // => ['orders', 'list', { status: 'open' }]
orderKeys.details() // => ['orders', 'detail']
orderKeys.detail('ord_1') // => ['orders', 'detail', 'ord_1']
orderKeys.custom('by-customer', 'ada') // => ['orders', 'by-customer', 'ada']
```

Invalidating a key also invalidates every key that starts with it. `orderKeys.lists()` covers every filtered list; `orderKeys.all` covers everything about orders. `keyMatches(prefix, key)` from `kitr/app` applies the same rule, if you need it in your own code:

```ts
import { keyMatches } from 'kitr/app'

keyMatches(['orders', 'list'], ['orders', 'list', { status: 'open' }]) // => true
keyMatches(['orders', 'detail'], ['orders', 'list']) // => false
```

A key must include every input that changes the result. A list filtered by status and page needs both in its key, or two different pages end up in one cache entry.

## Pass input to a query

The first argument of `key` and `fetch` is the query's input. Type it once on `key`, and `options(input)`, `key(input)` and `fetch(input)` all expect it:

```ts
// app/features/orders/queries.ts
import { createKeys } from 'kitr/app'
import { defineQuery } from 'kitr/query'
import type { Order } from './types'

export const orderKeys = createKeys('orders')

export const orderQuery = defineQuery({
  key: (id: string) => orderKeys.detail(id),
  fetch: async (id, { signal }) => {
    const res = await fetch(`/api/orders/${id}`, { signal })
    return (await res.json()) as Order
  },
})

export const ordersQuery = defineQuery({
  key: (filters: { status?: Order['status']; page: number }) => orderKeys.list(filters),
  fetch: async (filters, { signal }) => {
    const params = new URLSearchParams({ page: String(filters.page) })
    if (filters.status) params.set('status', filters.status)
    const res = await fetch(`/api/orders?${params}`, { signal })
    return (await res.json()) as Order[]
  },
})
```

`fetch` receives a `signal`. Pass it on: when a component unmounts or the key changes mid-flight, TanStack aborts the request.

You rarely write `fetch` by hand. Each data source package produces the contract for you, and you pass it straight to `defineQuery`:

| Source | Package | Contract |
| --- | --- | --- |
| An existing REST API | [HTTP](/packages/http) | `defineQuery(httpQuery(http, { path: 'orders', key: () => orderKeys.list() }))` |
| Your own API routes | [API](/packages/api) | `defineQuery(api.orders.index.query())` |
| A server action | [Actions](/packages/actions) | `defineQuery(listOrders.query())` |
| A realtime channel | [Realtime](/packages/realtime) | `useChannel(realtime(), orderChannel, params)` |

Components never learn which source they read from. Swap a REST endpoint for a server action and no component changes.

## Read data in a component

`useQuery` returns `data` as `undefined` until the first load finishes, plus flags for every state. It is the hook to use when the component draws its own loading and error states:

```tsx
// app/features/orders/order-summary.tsx
import { useQuery } from 'kitr/query'
import { orderQuery } from './queries'

export function OrderSummary({ id }: { id: string }) {
  const { data: order, isPending, isError, error, isFetching } = useQuery(orderQuery.options(id))
  if (isPending) return <p>Loading…</p>
  if (isError) return <p role="alert">{error.message}</p>
  return (
    <p>
      {order.customer} owes ${order.total} {isFetching ? '(refreshing)' : null}
    </p>
  )
}
```

`useSuspenseQuery` returns `data` that is always defined. The component suspends until the data arrives, and the nearest `<Suspense>` boundary shows the fallback. A route's `pendingComponent` acts as that boundary:

```tsx
// app/features/orders/order-list.tsx
import { useSuspenseQuery } from 'kitr/query'
import { ordersQuery } from './queries'

export function OrderList({ page }: { page: number }) {
  const { data: orders } = useSuspenseQuery(ordersQuery.options({ page }))
  return (
    <ul>
      {orders.map((order) => (
        <li key={order.id}>{order.customer}</li>
      ))}
    </ul>
  )
}
```

Errors thrown by a suspense query go to the nearest error boundary, such as the route's `errorComponent`.

`options()` returns a plain object, so you can spread it and add any TanStack option for one call site. Here only the count of open orders is selected, and the component re-renders only when that number changes:

```tsx
// app/features/orders/open-count.tsx
import { useQuery } from 'kitr/query'
import { ordersQuery } from './queries'

export function OpenOrderCount() {
  const { data: count } = useQuery({
    ...ordersQuery.options({ status: 'open', page: 1 }),
    select: (orders) => orders.length,
    refetchInterval: 60_000,
  })
  return <span>{count ?? 0} open</span>
}
```

## Load data before the page renders

Start the request in the route's loader so the data arrives with the page instead of after it. The router gives every loader `context.queryClient`, the same client the components read from:

```tsx
// app/routes/orders/$orderId.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useSuspenseQuery } from 'kitr/query'
import { orderQuery } from '#app/features/orders/queries'

export const Route = createFileRoute('/orders/$orderId')({
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData(orderQuery.options(params.orderId)),
  component: OrderPage,
})

function OrderPage() {
  const { orderId } = Route.useParams()
  const { data: order } = useSuspenseQuery(orderQuery.options(orderId))
  return <h1>Order {order.id} for {order.customer}</h1>
}
```

`ensureQueryData` returns cached data when there is some and fetches otherwise. With server rendering, the server runs the loader, renders with the data and sends it along with the HTML, so the browser does not fetch it again.

Don't `await` data the page can live without. Start it with `prefetchQuery` and let the component suspend on it, so the page renders without waiting:

```tsx
// app/routes/orders/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { ordersQuery } from '#app/features/orders/queries'
import { OrderList } from '#app/features/orders/order-list'
import { OpenOrderCount } from '#app/features/orders/open-count'

export const Route = createFileRoute('/orders/')({
  loader: async ({ context }) => {
    // Needed for the first paint: wait for it.
    await context.queryClient.ensureQueryData(ordersQuery.options({ page: 1 }))
    // Nice to have: start it, don't wait.
    void context.queryClient.prefetchQuery(ordersQuery.options({ status: 'open', page: 1 }))
  },
  component: () => (
    <>
      <OpenOrderCount />
      <OrderList page={1} />
    </>
  ),
})
```

The kitr router preloads a route's loader when the pointer rests on a link to it, so most pages open with their data already in the cache.

## Change data with a mutation

A mutation changes something on the server: pay an invoice, rename a project, ship an order. Define it next to the queries, then run it in a component with `useKitrMutation`:

```ts
// app/features/orders/queries.ts
import { defineMutation } from 'kitr/query'
import type { Order } from './types'

export const shipOrder = defineMutation({
  mutate: async (input: { id: string; carrier: string }) => {
    const res = await fetch(`/api/orders/${input.id}/ship`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ carrier: input.carrier }),
    })
    return (await res.json()) as Order
  },
})
```

```tsx
// app/features/orders/ship-button.tsx
import { useKitrMutation } from 'kitr/query'
import { shipOrder } from './queries'

export function ShipButton({ id }: { id: string }) {
  const ship = useKitrMutation(shipOrder)
  return (
    <>
      <button
        type="button"
        disabled={ship.isPending}
        onClick={() => ship.mutate({ id, carrier: 'UPS' })}
      >
        {ship.isPending ? 'Shipping…' : 'Ship order'}
      </button>
      {ship.error ? <p role="alert">{ship.error.message}</p> : null}
    </>
  )
}
```

`useKitrMutation` returns TanStack's [`useMutation`](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) result: `mutate`, `mutateAsync`, `isPending`, `error`, `data` and `reset`. Pass any `useMutation` option except `mutationFn` as the second argument. Your `onSuccess` runs after the mutation's own cache effects, so the cache is already updated when it runs:

```tsx
// app/features/orders/use-ship-and-return.ts
import { useNavigate } from '@tanstack/react-router'
import { useKitrMutation } from 'kitr/query'
import { shipOrder } from './queries'

export function useShipAndReturn() {
  const navigate = useNavigate()
  return useKitrMutation(shipOrder, {
    onSuccess: (order) => navigate({ to: '/orders/$orderId', params: { orderId: order.id } }),
    onError: (error) => console.warn('Ship failed', error.message),
  })
}
```

## Refresh what a mutation changed

After a save, every screen showing the changed data must update. Instead of telling each component to refetch, the mutation declares its **effects** on the cache, and `useKitrMutation` applies them when the mutation succeeds:

```ts
// app/features/orders/queries.ts
import { defineMutation } from 'kitr/query'
import { orderKeys } from './keys'
import type { Order } from './types'

export const shipOrder = defineMutation({
  mutate: async (input: { id: string; carrier: string }) => {
    const res = await fetch(`/api/orders/${input.id}/ship`, {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify({ carrier: input.carrier }),
    })
    return (await res.json()) as Order
  },
  effects: (order, input) => ({
    set: [{ key: orderKeys.detail(input.id), data: order }],
    invalidate: [orderKeys.lists()],
  }),
})
```

| Effect | What it does | Use it when |
| --- | --- | --- |
| `set` | Writes `data` into the entry at `key` with no request. | The server returned the new value. |
| `invalidate` | Marks every entry starting with the key as stale. Entries on screen refetch now; the rest refetch next time they are used. | You don't have the new value, or many entries changed (every filtered list). |
| `remove` | Drops the entries from the cache. The next read fetches from scratch. | The thing was deleted. |

They run in that order: `set`, then `remove`, then `invalidate`. The mutation's `onSuccess` waits for the invalidated queries to refetch, so `ship.isPending` stays `true` until the lists on screen have refetched.

`effects` is either a function of the result and the input, as above, or a plain object when the effects never depend on the result:

```ts
// app/features/invoices/queries.ts
import { createKeys } from 'kitr/app'
import { defineMutation } from 'kitr/query'

export const invoiceKeys = createKeys('invoices')

export const deleteInvoice = defineMutation({
  mutate: async (id: string) => {
    await fetch(`/api/invoices/${id}`, { method: 'DELETE' })
  },
  effects: { invalidate: [invoiceKeys.lists()], remove: [invoiceKeys.details()] },
})
```

Don't call `queryClient.invalidateQueries` in the component after `mutate`. The next component that runs the same mutation forgets to, and its screen shows stale data. Declare the effect on the mutation once.

`effectsFor(result, input)` returns the effects a result would produce, which helps when you test them:

```ts
import { shipOrder } from '#app/features/orders/queries'

shipOrder.effectsFor(
  { id: 'ord_2', customer: 'Grace', total: 80, status: 'shipped' },
  { id: 'ord_2', carrier: 'UPS' },
)
// => {
//   set: [{ key: ['orders', 'detail', 'ord_2'], data: { id: 'ord_2', customer: 'Grace', total: 80, status: 'shipped' } }],
//   invalidate: [['orders', 'list']],
// }
```

## Combine effects from several resources

Shipping an order also changes the customer's open invoice. `mergeEffects` from `kitr/app` joins several effects into one, concatenating each list:

```ts
// app/features/orders/queries.ts
import { mergeEffects } from 'kitr/app'
import { defineMutation } from 'kitr/query'
import { invoiceKeys } from '#app/features/invoices/queries'
import { orderKeys } from './keys'
import type { Order } from './types'

export const shipOrder = defineMutation({
  mutate: async (input: { id: string; carrier: string }) => {
    const res = await fetch(`/api/orders/${input.id}/ship`, { method: 'POST' })
    return (await res.json()) as Order
  },
  effects: (order) =>
    mergeEffects(
      { set: [{ key: orderKeys.detail(order.id), data: order }] },
      { invalidate: [orderKeys.lists()] },
      { invalidate: [invoiceKeys.lists()] },
    ),
})
// effects for ord_2 => { set: [...], invalidate: [['orders', 'list'], ['invoices', 'list']] }
```

`mergeEffects` skips `undefined`, so a helper that returns no effect for some inputs can sit in the list.

## Update the cache outside a mutation

Sometimes the change comes from somewhere that is not a mutation: a message from a service worker, a `postMessage` from another window, a test. `applyCacheEffect` applies the same effect shape to any client, and `invalidate` marks several keys stale in one call:

```ts
// app/features/orders/sync.ts
import { app } from '#app/app'
import { applyCacheEffect, invalidate } from 'kitr/query'
import { invoiceKeys } from '#app/features/invoices/queries'
import { orderKeys } from './keys'

const queryClient = app.container.use('queryClient')

export async function onOrderPaidElsewhere(orderId: string) {
  await applyCacheEffect(queryClient, {
    remove: [orderKeys.detail(orderId)],
    invalidate: [orderKeys.lists()],
  })
}

export function refreshBilling() {
  return invalidate(queryClient, orderKeys.all, invoiceKeys.all)
}
```

In a component, read the client with TanStack's `useQueryClient()` instead of the container. For anything not covered by effects, the client is TanStack's own [`QueryClient`](https://tanstack.com/query/latest/docs/reference/QueryClient): `setQueryData`, `getQueryData`, `cancelQueries` and the rest all work.

## Update the screen before the server answers

For an optimistic update, write the expected value before the request, and roll back if it fails. Pass TanStack's `onMutate` and `onError` through `useKitrMutation`; the mutation's own effects still run on success:

```tsx
// app/features/orders/use-mark-paid.ts
import { defineMutation, useKitrMutation, useQueryClient } from 'kitr/query'
import { orderKeys } from './keys'
import type { Order } from './types'

export const markPaid = defineMutation({
  mutate: async (id: string) => {
    const res = await fetch(`/api/orders/${id}/pay`, { method: 'POST' })
    return (await res.json()) as Order
  },
  effects: (order) => ({
    set: [{ key: orderKeys.detail(order.id), data: order }],
    invalidate: [orderKeys.lists()],
  }),
})

export function useMarkPaid(id: string) {
  const queryClient = useQueryClient()
  const key = orderKeys.detail(id)
  return useKitrMutation(markPaid, {
    onMutate: async () => {
      await queryClient.cancelQueries({ queryKey: key })
      const previous = queryClient.getQueryData<Order>(key)
      if (previous) queryClient.setQueryData<Order>(key, { ...previous, status: 'paid' })
      return { previous }
    },
    onError: (_error, _input, snapshot) => {
      // `snapshot` is what onMutate returned.
      const previous = (snapshot as { previous?: Order } | undefined)?.previous
      if (previous) queryClient.setQueryData(key, previous)
    },
  })
}
```

## Use a query or mutation by name

[Server actions](/packages/actions) register every `defineQuery('orders.list', ...)` and `defineMutation('orders.ship', ...)` under its name, and `kitr types` writes those names into `.kitr/actions.ts` so they are typed. Every hook in `kitr/query` then takes the name as its first argument, the input as the second, and TanStack overrides as the third:

```tsx
// app/components/open-orders.tsx
import { queryOptions, useMutation, useQuery, useSuspenseQuery } from 'kitr/query'

export function OpenOrders() {
  const { data } = useQuery('orders.list', { status: 'open' }, { refetchInterval: 10_000 })
  const { data: orders } = useSuspenseQuery('orders.list', { status: 'open' })
  const ship = useMutation('orders.ship', { onSuccess: () => toast('Shipped') })
  return <ul>{orders.map((o) => <li key={o.id}>{o.customer}</li>)}</ul>
}

// In a loader:
const options = queryOptions('orders.list', { status: 'open' })
```

The input is optional when every field of it is optional. A name that is not registered, or a mutation name given to `useQuery`, is a type error; at run time the hook throws `[kitr/query] "orders.lsit" is not registered` with the names that are.

`useMutation(definition)` works the same way as `useKitrMutation(definition)`: both apply the mutation's cache effects, then your own `onSuccess`. Outside React, `call` runs an operation by name. A query fetches, a mutation mutates; in the browser it is a request, on the server the handler runs in-process:

```ts
import { call } from 'kitr/query'

const open = await call('orders.list', { status: 'open' })
// => [{ id: 'ord_2', customer: 'Grace', total: 80, status: 'open' }]
await call('orders.ship', { id: 'ord_2', carrier: 'UPS' })
```

Every hook also accepts the imported definition in place of the name, `useQuery(listOrders, input)`, and plain TanStack options as before. The three forms produce the same query options, so a component and a loader using different forms share one cache entry.

## Call a source without the cache

`fetch(input, signal?)` on a query and `mutate(input)` on a mutation call the source directly. They skip the cache, skip effects and do not normalise errors to `KitrError`. Use them in scripts, server code or a test of the source itself:

```ts
// scripts/print-open-orders.ts
import { ordersQuery, shipOrder } from '#app/features/orders/queries'

const open = await ordersQuery.fetch({ status: 'open', page: 1 })
// => [{ id: 'ord_2', customer: 'Grace', total: 80, status: 'open' }]

await shipOrder.mutate({ id: 'ord_2', carrier: 'UPS' })
// The cache is untouched: no effects ran.
```

`key(input)` returns the cache key, and `contract` holds the full contract with its `kind` and `source` (`'http'`, `'api'`, `'action'`, `'socket'`, or `undefined` for a hand-written one).

## Subscribe to live updates

A subscription is a stream of events whose effects land in the same cache that `useQuery` reads. When Linus ships an order in his browser, the order page Ada has open updates without a refetch.

Define it with the input and event types, a `key`, a `subscribe` function that returns an unsubscribe function, and `effects` that map each event to cache changes:

```ts
// app/features/orders/subscriptions.ts
import { defineSubscription } from 'kitr/query'
import { orderKeys } from './keys'
import type { Order } from './types'

type OrderEvent = { type: 'updated'; order: Order } | { type: 'deleted'; id: string }

export const orderEvents = defineSubscription<string, OrderEvent>({
  key: (teamId) => ['order-events', teamId],
  subscribe: (teamId, { next, error }) => {
    const source = new EventSource(`/api/teams/${teamId}/order-events`)
    source.onmessage = (message) => next(JSON.parse(message.data))
    source.onerror = () => error?.({ code: 'NETWORK', message: 'Order feed lost', status: 0 })
    return () => source.close()
  },
  effects: (event) =>
    event.type === 'updated'
      ? { set: [{ key: orderKeys.detail(event.order.id), data: event.order }], invalidate: [orderKeys.lists()] }
      : { remove: [orderKeys.detail(event.id)], invalidate: [orderKeys.lists()] },
})
```

Then subscribe from the component that needs it. The hook subscribes on mount, unsubscribes on unmount and resubscribes only when the input's key changes:

```tsx
// app/features/orders/live-orders.tsx
import { useSubscription } from 'kitr/query'
import { OrderList } from './order-list'
import { orderEvents } from './subscriptions'

export function LiveOrders({ teamId }: { teamId: string }) {
  const live = useSubscription(orderEvents, teamId, {
    onEvent: (event) => console.info('order event', event.type),
    onError: (error) => console.warn(error.code, error.message),
  })
  return (
    <>
      <p>{live.status === 'open' ? 'Live' : live.status === 'error' ? 'Offline' : 'Paused'}</p>
      <OrderList page={1} />
    </>
  )
}
```

| Option | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Set `false` to not subscribe, for example until the user opens the panel. |
| `onEvent` | | Called with every event, after it is stored as `lastEvent`. |
| `onError` | | Called with a `KitrErrorShape` when the source reports an error. |

The hook returns `{ status, lastEvent, error }`. `status` is `'idle'` before subscribing and after unmount, `'open'` while subscribed, and `'error'` after the source calls `error`. You rarely write `subscribe` by hand: [Realtime](/packages/realtime) channels produce the same shape from a channel definition, with WebSocket, Socket.IO or SSE underneath.

## Handle errors

Every failure from `options()` and `useKitrMutation`, whatever its source, reaches you as a `KitrError` from `kitr/app` with a `code`, `status`, `message` and, for validation failures, `fieldErrors`:

```tsx
// app/features/orders/order-error.tsx
import { isKitrError } from 'kitr/app'

export function OrderError({ error }: { error: Error }) {
  if (isKitrError(error) && error.code === 'NOT_FOUND') return <p>This order no longer exists.</p>
  if (isKitrError(error) && error.code === 'FORBIDDEN') return <p>Ask Grace for access to this team.</p>
  return <p role="alert">{error.message}</p>
}
```

A thrown wire shape such as `{ code: 'CONFLICT', message: 'Order already shipped', status: 409 }` becomes a `KitrError` with that code. A `TypeError` whose message mentions fetch (Chrome's `Failed to fetch`) becomes `NETWORK` with status `0`, and an `AbortError` becomes `TIMEOUT`. Anything else becomes `INTERNAL` with the original message.

| Code | Status | Retried by queries |
| --- | --- | --- |
| `BAD_REQUEST` | 400 | no |
| `UNAUTHORIZED` | 401 | no |
| `FORBIDDEN` | 403 | no |
| `NOT_FOUND` | 404 | no |
| `TIMEOUT` | 408 | no |
| `CONFLICT` | 409 | no |
| `VALIDATION` | 422 | no |
| `RATE_LIMITED` | 429 | no |
| `INTERNAL` | 500 | twice |
| `UNAVAILABLE` | 503 | twice |
| `NETWORK` | 0 | twice |

Queries retry only failures that might pass on a second try. A 4xx means the request itself is wrong, so it fails at once and the user sees the error without a wait. Mutations are not retried. [Forms](/packages/forms) puts a `VALIDATION` error's `fieldErrors` under the right inputs, so a `mutateAsync` inside a form's `onSubmit` needs no error code of its own.

## Tune caching per query

`staleTime` on the contract overrides the config default for one query. Use a long one for data that rarely changes and `0` for data that must always be fresh:

```ts
// app/features/teams/queries.ts
import { createKeys } from 'kitr/app'
import { defineQuery } from 'kitr/query'

export const teamKeys = createKeys('teams')

export const teamsQuery = defineQuery({
  key: () => teamKeys.list(),
  fetch: async (_input, { signal }) => {
    const res = await fetch('/api/teams', { signal })
    return (await res.json()) as { id: string; name: string }[]
  },
  // Teams change rarely: serve them from the cache for ten minutes.
  staleTime: 10 * 60_000,
})
```

`teamsQuery.options()` now carries `staleTime: 600000`. A query without its own `staleTime` uses the config value. For one call site, spread the options and override them:

```tsx
// app/features/teams/team-picker.tsx
import { useQuery } from 'kitr/query'
import { teamsQuery } from './queries'

export function TeamPicker() {
  // This screen edits teams, so it always wants the latest list.
  const { data: teams = [] } = useQuery({ ...teamsQuery.options(), staleTime: 0 })
  return (
    <select>
      {teams.map((team) => (
        <option key={team.id} value={team.id}>
          {team.name}
        </option>
      ))}
    </select>
  )
}
```

## Server rendering

On the server, every request gets its own `QueryClient`. The provider binds `queryClient` as a scoped binding, so each forked app that renders a request builds a fresh cache, and one customer's orders can never render into another customer's page. In the browser there is one app, so there is one client for the whole session.

Nothing in your code changes for this. Read the client through `context.queryClient` in loaders and `useQueryClient()` in components, and you always get the one for the current request. Don't import `app` and call `app.container.use('queryClient')` from code that runs during a server render: it reads the root app's client, not the request's.

## Testing

In a test, boot an app with the query provider, seed the cache with the data the component needs, and render inside the app's providers. `createTestApp` from `kitr/testing` boots the app; `renderWithKitr` from `kitr/testing/react` renders inside `KitrProvider` and takes `queryData` as `[key, data]` pairs. Seeded data is fresh for 30 seconds, so the component reads it without calling `fetch`:

```tsx
// app/features/orders/orders.test.tsx
import { act, renderHook, screen } from '@testing-library/react'
import { createKeys } from 'kitr/app'
import {
  defineMutation,
  defineQuery,
  queryProvider,
  useKitrMutation,
  useSuspenseQuery,
} from 'kitr/query'
import { KitrProvider } from 'kitr/react'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { type ReactNode, Suspense } from 'react'
import { describe, expect, it, vi } from 'vitest'

interface Order {
  id: string
  customer: string
  status: 'open' | 'shipped'
}

const orderKeys = createKeys('orders')
const fetchOrders = vi.fn(async (): Promise<Order[]> => [])
const ordersQuery = defineQuery({ key: () => orderKeys.list(), fetch: fetchOrders })
const shipOrder = defineMutation({
  mutate: async (id: string): Promise<Order> => ({ id, customer: 'Grace', status: 'shipped' }),
  effects: (order) => ({
    set: [{ key: orderKeys.detail(order.id), data: order }],
    invalidate: [orderKeys.lists()],
  }),
})

function OrderList() {
  const { data: orders } = useSuspenseQuery(ordersQuery.options())
  return (
    <ul>
      {orders.map((order) => (
        <li key={order.id}>{order.customer}</li>
      ))}
    </ul>
  )
}

describe('orders', () => {
  it('renders seeded orders without fetching', async () => {
    const app = await createTestApp({ providers: [queryProvider] })
    renderWithKitr(
      <Suspense fallback="Loading">
        <OrderList />
      </Suspense>,
      { app, queryData: [[orderKeys.list(), [{ id: 'ord_1', customer: 'Ada', status: 'open' }]]] },
    )
    expect(await screen.findByText('Ada')).toBeTruthy()
    expect(fetchOrders).not.toHaveBeenCalled()
  })

  it('shipping writes the order and marks every list stale', async () => {
    const app = await createTestApp({ providers: [queryProvider] })
    const queryClient = app.container.use('queryClient')
    queryClient.setQueryData(orderKeys.list(), [])
    const wrapper = ({ children }: { children: ReactNode }) => (
      <KitrProvider app={app}>{children}</KitrProvider>
    )
    const { result } = renderHook(() => useKitrMutation(shipOrder), { wrapper })

    await act(() => result.current.mutateAsync('ord_2'))

    expect(queryClient.getQueryData(orderKeys.detail('ord_2'))).toEqual({
      id: 'ord_2',
      customer: 'Grace',
      status: 'shipped',
    })
    expect(queryClient.getQueryState(orderKeys.list())?.isInvalidated).toBe(true)
  })
})
```

The assertions you will write most:

| To check | Assert |
| --- | --- |
| A mutation wrote an entry | `queryClient.getQueryData(key)` equals the new value |
| A mutation marked entries stale | `queryClient.getQueryState(key)?.isInvalidated` is `true` |
| A mutation removed an entry | `queryClient.getQueryData(key)` is `undefined` |
| A component did not refetch | the `fetch` mock was not called |
| A failure reached the UI | `result.current.error` is a `KitrError` with the expected `code` |

To test effects without React, call `effectsFor` and apply the result to a bare client. No provider is needed:

```ts
// app/features/orders/effects.test.ts
import { applyCacheEffect, QueryClient } from 'kitr/query'
import { expect, it } from 'vitest'
import { orderKeys } from './keys'
import { shipOrder } from './queries'

it('shipping replaces the order and refreshes lists', async () => {
  const queryClient = new QueryClient()
  queryClient.setQueryData(orderKeys.list({ status: 'open' }), [{ id: 'ord_2' }])
  const shipped = { id: 'ord_2', customer: 'Grace', total: 80, status: 'shipped' as const }

  await applyCacheEffect(queryClient, shipOrder.effectsFor(shipped, { id: 'ord_2', carrier: 'UPS' }))

  expect(queryClient.getQueryData(orderKeys.detail('ord_2'))).toEqual(shipped)
  expect(queryClient.getQueryState(orderKeys.list({ status: 'open' }))?.isInvalidated).toBe(true)
})
```

To fake the network itself rather than the query, use [Mocks](/packages/mocks): its handlers answer `fetch` in tests and in the browser, so the query runs end to end.

## Extend

Every data source is a function that returns a contract. To add a source kitr does not ship, such as a GraphQL endpoint or a vendor SDK, write one function per kind and pass its result to `defineQuery`, `defineMutation` or `defineSubscription`. The types are `QueryContract`, `MutationContract` and `SubscriptionContract` from `kitr/app` (see the [API reference](/packages/query/api)):

| Member | Kind | Description |
| --- | --- | --- |
| `key(input)` | query, subscription | The cache key. Include every input that changes the result. |
| `fetch(input, { signal })` | query | Load the data. Pass `signal` to the request so TanStack can cancel it. |
| `mutate(input)` | mutation | Make the change and return the result. |
| `subscribe(input, { next, error })` | subscription | Start the stream, call `next` per event, return a function that stops it. |
| `effects` | mutation, subscription | Cache effects after a success or per event. |
| `staleTime` | query | Freshness for this query, overriding the config. |
| `source` | all | A label for devtools, stored in TanStack's `meta.source`. |

This source turns a GraphQL operation into a query contract:

```ts
// app/lib/graphql.ts
import { KitrError, type QueryContract, type QueryKey } from 'kitr/app'

interface GraphqlQueryOptions<TInput> {
  document: string
  key: (input: TInput) => QueryKey
  variables?: (input: TInput) => Record<string, unknown>
  staleTime?: number
}

export function graphqlQuery<TInput = void, TOutput = unknown>(
  opts: GraphqlQueryOptions<TInput>,
): Omit<QueryContract<TInput, TOutput>, 'kind'> {
  return {
    source: 'graphql',
    key: opts.key,
    staleTime: opts.staleTime,
    fetch: async (input, { signal }) => {
      const res = await fetch('https://api.acme.com/graphql', {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ query: opts.document, variables: opts.variables?.(input) }),
        signal,
      })
      if (!res.ok) throw KitrError.fromStatus(res.status)
      const body = (await res.json()) as { data?: TOutput; errors?: { message: string }[] }
      if (body.errors?.length) throw new KitrError('BAD_REQUEST', body.errors[0]!.message)
      return body.data as TOutput
    },
  }
}
```

```ts
// app/features/projects/queries.ts
import { createKeys } from 'kitr/app'
import { defineQuery } from 'kitr/query'
import { graphqlQuery } from '#app/lib/graphql'

export const projectKeys = createKeys('projects')

export const projectsQuery = defineQuery(
  graphqlQuery<{ teamId: string }, { projects: { id: string; name: string }[] }>({
    document: 'query ($teamId: ID!) { projects(teamId: $teamId) { id name } }',
    key: ({ teamId }) => projectKeys.list({ teamId }),
    variables: ({ teamId }) => ({ teamId }),
  }),
)
```

Throw a `KitrError` (or anything with `code`, `message` and `status`) so components and forms see the same shape as every other source. Whatever you throw is normalised anyway, so a plain `Error` still arrives as `INTERNAL`.

## Devtools

With [Devtools](/packages/devtools) installed, the provider adds a **Query** panel in development. Its badge shows how many queries are fetching (`2↻`) or, when idle, how many are cached. The panel lists every cached query, newest first, with its key, a status badge (`fetching`, `error`, `stale` or `fresh`), its observer count and how long ago it updated. Select a row to see its data or error, and to invalidate, refetch or remove that one entry. Two panel actions apply to the whole cache: **Invalidate all queries** and **Clear cache**.

Failed mutations are logged to the Log panel under `query` as `mutation failed: <mutationKey>` with the error attached.

## Next steps

- [API reference](/packages/query/api)
- [TanStack Query docs](https://tanstack.com/query/latest/docs/framework/react/overview): everything there works as written, imported from `kitr/query`.
- [HTTP](/packages/http): turn REST endpoints into queries and mutations.
- [Realtime](/packages/realtime): live channels whose events update the cache.
- [Loading and saving data](/docs/data): how every kitr data source shares one contract.


# React API

Source: https://kitr.dev/packages/react/api

Every export of `kitr/react`, read from the published type definitions. The [guide](/packages/react) shows them in use.

## kitr/react

### createApp

```ts
function createApp(options?: CreateAppOptions): KitrApp;
```

Creates the app object that owns the container, config and providers. Call `boot()` on it
before reading services; one app per client, per server process and per test.

### KitrBoot

```ts
function KitrBoot({ app, children, fallback }: KitrProviderProps & {
  fallback?: ReactNode;
}): import("react").JSX.Element;
```

Boot an app inside React. Renders `fallback` until boot completes.
Use in client-only apps; server-rendered apps boot before rendering.

### KitrProvider

```ts
function KitrProvider({ app, children }: KitrProviderProps): import("react").JSX.Element;
```

Puts the app in context and renders every provider's `wrap()` around children.
Boot the app first (`await app.boot()`) when you can; otherwise it suspends until boot completes.

### useApp

```ts
function useApp(): KitrApp;
```

The app in context: its container, config, env, mode, environment and platform.
Throws when the component is not rendered inside `KitrProvider` (or `KitrBoot`, or the router).

### useConfig

```ts
function useConfig<K extends Parameters<KitrApp['config']['get']>[0]>(key: K): import("@kitr/core").ConfigOf<K>;
```

Read one package's config, as exported by `config/<name>.ts`, typed from `ConfigRegistry`.
Throws when that config does not exist; use `useApp().config.get(key, fallback)` for optional config.

### useService

```ts
function useService<K extends Parameters<KitrApp['container']['use']>[0]>(key: K): import("@kitr/core").Binding<K>;
```

Read a container binding from a component, typed from `ContainerBindings` (`useService('http')`).
The binding must be resolved, which it is after boot; an unknown key throws.

### KitrApp

```ts
class KitrApp {
  readonly container: Container;
  readonly config: ConfigStore;
  readonly environment: AppEnvironment;
  readonly mode: AppMode;
  readonly env: Record<string, unknown>;
  readonly providers: KitrProvider[];
  /** Native drivers registered by platform providers, resolved by capability packages. */
  readonly drivers: DriverRegistry;
  /** The platform name from kitrrc.ts this bundle runs as, when known. */
  readonly platform: PlatformName | undefined;
  /** The process-wide operation registry (see `operations` in `@kitr/core`). */
  readonly operations: OperationRegistry;
  private inputs;
  private phase;
  private readying;
  private booting?;
  constructor(options?: CreateAppOptions);
  get isClient(): boolean;
  get isServer(): boolean;
  get isDevelopment(): boolean;
  get isProduction(): boolean;
  /** Add a provider before boot. */
  use(provider: ProviderInput): this;
  /** register → boot. Idempotent: concurrent callers share one boot. */
  boot(): Promise<this>;
  /** Server only: tell providers the server is serving. Idempotent: runs each `ready` once. */
  ready(): Promise<this>;
  /** Server only: run providers' `shutdown` in reverse order. */
  shutdown(): Promise<void>;
  /** Compose every provider's `wrap`, outermost first. */
  wrap(children: KitrNode): KitrNode;
  /** A request- or test-scoped app that shares providers and config but has its own instances. */
  fork(): KitrApp;
  get status(): Phase;
}
```

The app object every provider sees. One per client, one per server process,
one per test. It owns the container, the config and the provider list.

### CreateAppOptions

```ts
interface CreateAppOptions {
  /** Providers to register, in order. Usually the list from `kitrrc.ts`. */
  providers?: ProviderInput[];
  /** Per-package config, keyed the way `config/<name>.ts` files are. */
  config?: Record<string, unknown>;
  /** client | server | test. Default: `test` under Vitest, `client` when `window` exists, otherwise `server`. */
  environment?: AppEnvironment;
  /** development | production | test. Default: from Vite's `import.meta.env.MODE` or `NODE_ENV`. */
  mode?: AppMode;
  /** Validated env object (from `createEnv`). Exposed as `app.env`. */
  env?: Record<string, unknown>;
  /** The platform name this bundle was built for (`kitr dev site` → `site`). Default: from `import.meta.env.KITR_PLATFORM`. */
  platform?: PlatformName;
  /**
   * Every named query and mutation, by name: the `operations` map `kitr types` writes to
   * `.kitr/actions.ts`. Registered process-wide, so `useQuery('projects.list')` and
   * `call('projects.update', input)` resolve anywhere.
   */
  operations?: Record<string, OperationLike>;
}
```

Options for `createApp()`: the providers to register, their config and the runtime details.

### KitrProviderProps

```ts
interface KitrProviderProps {
  /** The app from `app/app.ts`. Every provider's `wrap()` is rendered around `children`. */
  app: KitrApp;
  /** The tree that can call `useApp`, `useService` and `useConfig`. */
  children: ReactNode;
}
```

Props of `KitrProvider` and `KitrBoot`: the app to put in context and the tree that reads it.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# React

Source: https://kitr.dev/packages/react

Every component in a real app needs something from outside itself: the HTTP client, the signed-in user, a feature flag, the theme. `kitr/react` puts the kitr app object in React context, so any component can read a service or a config file with one hook, without importing singletons, prop-drilling or writing a context of its own. It is built on [React](https://react.dev) and adds `KitrProvider`, `KitrBoot` and three hooks: `useApp`, `useService` and `useConfig`.

It runs on the client, and on the server during server rendering. A server-only project (the `server` kit) has no React at all; use [server](/packages/server) and reach services through `app.container` there.

This guide follows Acme's billing app at `app.acme.com`: Ada adds a `billing` service that loads invoices, and every component reaches it through the app.

## Install

Every UI kit (`blank`, `app`, `fullstack`, `saas`, `site`, `realtime`, `desktop`, `mobile`) includes React, and the web, desktop and mobile platforms add it through the [router](/packages/router), which requires it. You only run this in a project that has none:

```sh
kitr add react
```

What `kitr add` does:

- Installs `@kitr/react`, `react` and `react-dom`, and as dev dependencies `@vitejs/plugin-react`, `@types/react` and `@types/react-dom`.
- Adds `'@kitr/react'` to `packages` in `kitrrc.ts`. React registers no provider, so `providers` is unchanged.
- Writes `app/env.ts`, which declares one public variable, `VITE_APP_NAME`, defaulting to your package name.
- Writes `app/app.ts`, which creates the app from the providers in `kitrrc.ts`, the files in `config/` and `app/env.ts`.
- Adds no config file, no variables to `.env.example`, no scripts and no `AGENTS.md` section.

`kitr add` never overwrites a file that exists, so an `app/env.ts` or `app/app.ts` you already have is kept. `kitr add react` asks no questions. It accepts the usual flags: `--no-install` skips the package manager and `--dry-run` prints what would change.

```sh
kitr add react --dry-run
```

`kitr remove react` removes the packages and the `kitrrc.ts` entry. It leaves `app/env.ts` and `app/app.ts` in place, because the rest of the app imports them.

## Configure

`kitr/react` has no config file. What it needs is the app object, which `kitr add react` writes to `app/app.ts`:

```ts
// app/app.ts
import { createApp } from 'kitr/app'
import { config } from 'virtual:kitr/config'
import { providers } from 'virtual:kitr/providers'
import { env } from './env'

/** One app object: providers from kitrrc.ts, config from config/*.ts, both as static imports. */
export const app = createApp({ providers, config, env })
```

`virtual:kitr/providers` is the `providers` list from `kitrrc.ts`, and `virtual:kitr/config` holds every `config/<name>.ts`, keyed by file name. The [`kitr()` Vite plugin](/docs/configuration) generates both.

`app/env.ts` is the environment file it passes in:

```ts
// app/env.ts
import { createEnv, env as e } from 'kitr/env'

/** Validated at startup. Public vars (VITE_*) ship to the browser; server vars throw if read there. */
export const env = createEnv({
  public: {
    VITE_APP_NAME: e.string({ default: 'acme-billing' }),
  },
  server: {},
})
```

You hand the app to React through the props of `KitrProvider` or `KitrBoot`:

| Option | Default | Description |
| --- | --- | --- |
| `app` | required | The `KitrApp` from `app/app.ts`. Both components put it in context and render every provider's `wrap()` around `children`. |
| `children` | required | The tree that can call `useApp`, `useService` and `useConfig`. |
| `fallback` | `null` | `KitrBoot` only. What renders while the app boots. |

`createApp` from `kitr/app` (also re-exported from `kitr/react`) takes these options:

| Option | Default | Description |
| --- | --- | --- |
| `providers` | `[]` | Providers, or lazy imports of them, in `kitrrc.ts` order. |
| `config` | `{}` | Per-package config keyed by package name, as in `config/<name>.ts`. |
| `env` | `{}` | The validated env object from `createEnv`. Exposed as `app.env`. |
| `environment` | detected | `'client'`, `'server'` or `'test'`. `'test'` under Vitest, `'client'` when `window` and `document` exist, otherwise `'server'`. |
| `mode` | detected | `'development'`, `'production'` or `'test'`, from Vite's `import.meta.env.MODE` or `NODE_ENV`. |
| `platform` | `import.meta.env.KITR_PLATFORM` | The platform name from `kitrrc.ts` this bundle runs as, such as `site`. |

## Read a service in your first component

With the router installed there is nothing to wire: `createKitrRouter` renders `KitrProvider` around every page. A component reads a service with `useService` and a config file with `useConfig`:

```tsx
// app/features/invoices/invoice-count.tsx
import { useConfig, useService } from 'kitr/react'
import { useEffect, useState } from 'react'

export function InvoiceCount() {
  const http = useService('http') // the ky instance from kitr/http
  const theme = useConfig('theme') // config/theme.ts
  const [count, setCount] = useState<number | null>(null)

  useEffect(() => {
    http
      .get('invoices')
      .json<{ id: string }[]>()
      .then((invoices) => setCount(invoices.length))
  }, [http])

  return (
    <p>
      {count === null ? 'Loading invoices…' : `${count} open invoices`} (theme: {theme.default})
    </p>
  )
}
```

Use it in any route:

```tsx
// app/routes/invoices.tsx
import { createFileRoute } from '@tanstack/react-router'
import { InvoiceCount } from '#app/features/invoices/invoice-count'

export const Route = createFileRoute('/invoices')({
  component: () => (
    <main>
      <h1>Invoices</h1>
      <InvoiceCount />
    </main>
  ),
})
```

Open `/invoices` and the page shows `3 open invoices (theme: system)`. Both hooks are typed: `useService('http')` returns ky's `KyInstance` because [http](/packages/http) declares that binding, and `useConfig('theme')` returns `ThemeConfig` because [theme](/packages/theme) declares that config. A name no installed package declares returns `unknown`.

For data, prefer [query](/packages/query) over `useEffect`; this example only shows where the service comes from.

## Mount the app without the router

On the client, when you render React yourself (a widget, a micro-frontend, a test page), wrap the root in `KitrBoot`:

```tsx
// app/main.tsx
import { KitrBoot } from 'kitr/react'
import { createRoot } from 'react-dom/client'
import { app } from './app'
import { InvoiceCount } from './features/invoices/invoice-count'

createRoot(document.getElementById('root')!).render(
  <KitrBoot app={app} fallback={<p>Starting Acme Billing…</p>}>
    <InvoiceCount />
  </KitrBoot>,
)
```

`KitrBoot` calls `app.boot()`, which runs every provider's `register` and then its `boot`. It renders `fallback` until that finishes and then renders `KitrProvider`. If the app has already booted, it renders the children on the first render and never shows the fallback.

If boot fails, `KitrBoot` rethrows the error during render, so the nearest React error boundary catches it.

## Boot before rendering

When you can await, boot first and render `KitrProvider` directly. Nothing suspends and the first render is complete:

```tsx
// app/main.tsx
import { KitrProvider } from 'kitr/react'
import { createRoot } from 'react-dom/client'
import { app } from './app'
import { InvoiceCount } from './features/invoices/invoice-count'

await app.boot()

createRoot(document.getElementById('root')!).render(
  <KitrProvider app={app}>
    <InvoiceCount />
  </KitrProvider>,
)
```

This is what `app/client.tsx` does in a router project: it boots the app, then hydrates the server's HTML, so the first client render matches what the server sent.

```tsx
// app/client.tsx
import { StartClient } from '@tanstack/react-start/client'
import { StrictMode, startTransition } from 'react'
import { hydrateRoot } from 'react-dom/client'
import { app } from './app'

/** Start's client entry, with the kitr app booted first so providers are ready when the tree hydrates. */
app.boot().then(() => {
  startTransition(() => {
    hydrateRoot(
      document,
      <StrictMode>
        <StartClient />
      </StrictMode>,
    )
  })
})
```

`app.boot()` is idempotent: every caller shares one boot, so calling it from `client.tsx`, the router and a test never runs a provider twice.

## Render before boot with Suspense

`KitrProvider` also accepts an app that has not booted. It suspends on the boot promise, so the nearest `<Suspense>` boundary shows its fallback until every provider is ready. TanStack Start relies on this, because it builds the router synchronously before anything has awaited `app.boot()`.

```tsx
// app/main.tsx
import { KitrProvider } from 'kitr/react'
import { Suspense } from 'react'
import { createRoot } from 'react-dom/client'
import { app } from './app'
import { InvoiceCount } from './features/invoices/invoice-count'

createRoot(document.getElementById('root')!).render(
  <Suspense fallback={<p>Starting Acme Billing…</p>}>
    <KitrProvider app={app}>
      <InvoiceCount />
    </KitrProvider>
  </Suspense>,
)
```

Without a `<Suspense>` boundary above it, React has nowhere to show the wait and throws. Use `KitrBoot` when you do not want to place a boundary yourself.

| You have | Use |
| --- | --- |
| The router | Nothing. `createKitrRouter` renders `KitrProvider`. |
| Your own root, and you can `await` | `await app.boot()`, then `KitrProvider`. |
| Your own root, and you cannot `await` | `KitrBoot` with a `fallback`. |
| A `<Suspense>` boundary already in place | `KitrProvider` with an unbooted app. |

## Read the app itself

`useApp()` returns the whole app. Reach for it when you need something that is not a single service or config file:

```tsx
// app/components/environment-badge.tsx
import { useApp } from 'kitr/react'

export function EnvironmentBadge() {
  const app = useApp()
  if (app.isProduction) return null
  return (
    <span>
      {app.mode} on {app.platform ?? 'unknown platform'} ({app.environment})
    </span>
  )
}
// In `kitr dev site`: "development on site (client)"
```

| Property | What it is |
| --- | --- |
| `app.container` | The service container: `use(key)`, `has(key)`, `make(key)`, `keys()`. |
| `app.config` | Every `config/<name>.ts`: `get(key, fallback?)`, `has(key)`. |
| `app.env` | The object from `app/env.ts`, untyped. Import `env` from `#app/env` for types. |
| `app.mode` | `'development'`, `'production'` or `'test'`. |
| `app.environment` | `'client'`, `'server'` or `'test'`. |
| `app.platform` | The platform name from `kitrrc.ts`, such as `site`, or `undefined`. |
| `app.isClient`, `app.isServer`, `app.isDevelopment`, `app.isProduction` | Shorthands for the four checks above. |
| `app.status` | `'created'`, `'registered'`, `'booted'`, `'ready'` or `'shutdown'`. |

For typed environment variables, import the env object directly rather than reading `app.env`:

```tsx
// app/components/app-title.tsx
import { env } from '#app/env'

export function AppTitle() {
  return <title>{env.VITE_APP_NAME}</title>
}
```

## Read config in a component

`useConfig(name)` returns what `config/<name>.ts` exports by default:

```tsx
// app/components/theme-color.tsx
import { useConfig } from 'kitr/react'

export function ThemeColorSwatch() {
  const { colors } = useConfig('theme')
  return <span style={{ background: colors?.light }} aria-label="Light theme color" />
}
```

When the file does not exist, `useConfig` throws `[kitr] Missing config "theme". Create config/theme.ts or pass it to createApp().` For optional config, read it through the app with a fallback instead:

```tsx
// app/components/billing-banner.tsx
import { useApp } from 'kitr/react'

export function BillingBanner() {
  const billing = useApp().config.get('billing', { currency: 'usd' })
  return <p>Invoices are billed in {billing.currency.toUpperCase()}.</p>
}
```

Config is static: it is read once when `app/app.ts` runs. A component that reads it never re-renders because of it.

## Register your own service

Your own services go in the same container as the packages' services. Ada's billing client is a plain class:

```ts
// app/billing/client.ts
export interface Invoice {
  id: string
  team: string
  total: number
  status: 'open' | 'paid'
}

export class BillingClient {
  constructor(private readonly baseUrl: string) {}

  async openInvoices(team: string): Promise<Invoice[]> {
    const res = await fetch(`${this.baseUrl}/teams/${team}/invoices?status=open`)
    return (await res.json()) as Invoice[]
  }
}
```

A provider binds it during `register`:

```ts
// app/providers/billing_provider.ts
import { defineProvider } from 'kitr/app'
import { BillingClient } from '#app/billing/client'

declare module '@kitr/core' {
  interface ContainerBindings {
    billing: BillingClient
  }
  interface ConfigRegistry {
    billing: { currency: 'usd' | 'eur' }
  }
}

export default defineProvider({
  name: 'billing',
  register(app) {
    app.container.singleton('billing', () => new BillingClient('https://api.acme.com'))
  },
})
```

The `ConfigRegistry` entry types `config/billing.ts` for `useConfig('billing')` and `app.config.get('billing')`, the same way packages type theirs.

List it in `kitrrc.ts`, after the package providers it depends on:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/web'],
  providers: [
    () => import('@kitr/web/provider'),
    () => import('#app/providers/billing_provider'),
  ],
  platforms: { site: web({ mode: 'spa' }) },
})
```

Every component can now use it, typed:

```tsx
// app/features/invoices/open-invoices.tsx
import { useService } from 'kitr/react'
import { useEffect, useState } from 'react'
import type { Invoice } from '#app/billing/client'

export function OpenInvoices({ team }: { team: string }) {
  const billing = useService('billing') // BillingClient
  const [invoices, setInvoices] = useState<Invoice[]>([])

  useEffect(() => {
    billing.openInvoices(team).then(setInvoices)
  }, [billing, team])

  return (
    <ul>
      {invoices.map((invoice) => (
        <li key={invoice.id}>
          {invoice.id}: ${invoice.total}
        </li>
      ))}
    </ul>
  )
}
```

`kitr make:provider billing` writes the provider file for you, at `app/providers/billing_provider.ts`, with `register`, `boot` and a commented `wrap`.

Augment `'@kitr/core'`, the module that declares `ContainerBindings`. Don't augment `'kitr/app'`: it re-exports `@kitr/core` with `export *`, and TypeScript does not merge an interface through a re-export, so `useService('billing')` stays `unknown`.

## Bind async services

`useService` is synchronous. A factory that returns a promise works because `app.boot()` resolves every binding before the first render, so by the time a component asks, the instance is cached:

```ts
// app/providers/billing_provider.ts
import { defineProvider } from 'kitr/app'
import { BillingClient } from '#app/billing/client'

export default defineProvider({
  name: 'billing',
  register(app) {
    app.container.singleton('billing', async () => {
      const res = await fetch('https://app.acme.com/billing-config.json')
      const { apiUrl } = (await res.json()) as { apiUrl: string }
      return new BillingClient(apiUrl)
    })
  },
})
```

If a component reads an async binding that is still resolving, `useService` throws `[kitr] Binding "billing" has an async factory; await container.make('billing') before use('billing').` That only happens when you render with an app that has not finished booting and you bound the service after boot. Bind in `register`, and boot before rendering.

## Wrap the tree from a provider

A provider can put its own React context around the whole app with `wrap()`. `KitrProvider` composes every provider's `wrap` in `kitrrc.ts` order: the first provider is the outermost. That is how the query client, theme, auth session, translations and error boundary all reach your components while the root stays one line.

```tsx
// app/providers/team_provider.tsx
import { defineProvider } from 'kitr/app'
import { createContext, type ReactNode, useContext } from 'react'

const TeamContext = createContext<{ team: string }>({ team: 'acme' })

export const useTeam = () => useContext(TeamContext)

export default defineProvider({
  name: 'team',
  wrap: (children) => (
    <TeamContext.Provider value={{ team: 'acme' }}>{children as ReactNode}</TeamContext.Provider>
  ),
})
```

With `providers: [query, theme, team]`, the rendered tree is `<QueryClientProvider><ThemeProvider><TeamContext.Provider>{children}`. `wrap` receives the app as its second argument, so it can read config and services:

```tsx
// app/providers/team_provider.tsx
import { defineProvider } from 'kitr/app'
import { createContext, type ReactNode, useContext } from 'react'

const TeamContext = createContext<{ team: string }>({ team: 'acme' })

export const useTeam = () => useContext(TeamContext)

export default defineProvider({
  name: 'team',
  wrap: (children, app) => (
    <TeamContext.Provider value={{ team: app.config.get('team', { slug: 'acme' }).slug }}>
      {children as ReactNode}
    </TeamContext.Provider>
  ),
})
```

Here `config/team.ts` is optional: without it, `app.config.get` returns the fallback. Declare `team` in `ConfigRegistry` as shown for `billing` above to type it.

`wrap` runs on every render of `KitrProvider`'s children, so keep it to rendering context providers. Do I/O in `boot`.

Don't add a second `<QueryClientProvider>` or `<ThemeProvider>` in your root component. The packages' providers already wrap the tree; a second one shadows theirs with a different instance.

## Reach the app outside components

Loaders, `beforeLoad` guards and plain modules are not React components, so they cannot call hooks. In a route, read the app from the router context:

```tsx
// app/routes/teams/$team/invoices.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/teams/$team/invoices')({
  loader: ({ context, params }) => context.app.container.use('billing').openInvoices(params.team),
  component: TeamInvoices,
})

function TeamInvoices() {
  const invoices = Route.useLoaderData()
  return <p>{invoices.length} open invoices for this team</p>
}
```

On the server, `createKitrRouter` forks the app per request, and `context.app` is that request's fork. Don't import `app` from `#app/app` inside a loader: on the server it is the shared app, and a request-scoped service such as the query cache would leak between visitors.

Outside routes, in client-only code such as an event handler set up at startup, import the app:

```ts
// app/billing/refresh.ts
import { app } from '#app/app'

export async function refreshOpenInvoices(team: string) {
  const billing = await app.container.make('billing')
  return billing.openInvoices(team)
}
```

`make()` awaits an async factory; `use()` does not. Both return the same cached instance.

## Errors

These are thrown during render, so React's nearest error boundary receives them. With the router, that is the route's error screen.

| Error | When | What to do |
| --- | --- | --- |
| `[kitr/react] useApp() must be used inside <KitrProvider>.` | `useApp`, `useService` or `useConfig` ran in a component outside `KitrProvider`. | Render the component under the router, `KitrProvider` or `KitrBoot`. In tests, use `renderWithKitr`. |
| `[kitr] No binding named "billing". Did you add the package that provides it?` | `useService(key)` for a key no provider registered. | `kitr add` the package, or list your provider in `kitrrc.ts`. |
| `[kitr] Binding "billing" has an async factory; await container.make('billing') before use('billing').` | The binding's factory returned a promise that has not resolved yet. | Boot before rendering, or `await app.container.make(key)` first. |
| `[kitr] Missing config "billing". Create config/billing.ts or pass it to createApp().` | `useConfig(key)` for a config file that does not exist. | Create the file, or use `useApp().config.get(key, fallback)`. |
| The provider's own error | A provider's `register` or `boot` threw inside `KitrBoot`. | Fix the provider. `KitrBoot` rethrows it so an error boundary shows it. |

## Testing

`renderWithKitr` from [testing](/packages/testing) renders a component inside `KitrProvider` with a test app. `createTestApp` creates and boots an app with `environment: 'test'`, so you pass it the same providers and config your component needs, or a stand-in service:

```tsx
// app/features/invoices/open-invoices.test.tsx
import { defineProvider } from 'kitr/app'
import { createTestApp, renderWithKitr } from 'kitr/testing/react'
import { describe, expect, it } from 'vitest'
import type { BillingClient } from '#app/billing/client'
import { OpenInvoices } from './open-invoices'

describe('OpenInvoices', () => {
  it('lists the team’s open invoices from the billing service', async () => {
    const billing = {
      openInvoices: async (team: string) => [
        { id: 'inv_1', team, total: 120, status: 'open' as const },
        { id: 'inv_2', team, total: 80, status: 'open' as const },
      ],
    } as unknown as BillingClient

    const app = await createTestApp({
      providers: [
        defineProvider({
          name: 'billing',
          register: (a) => void a.container.value('billing', billing),
        }),
      ],
    })

    const screen = renderWithKitr(<OpenInvoices team="acme" />, { app })

    expect(await screen.findByText('inv_1: $120')).toBeTruthy()
    expect(screen.getByText('inv_2: $80')).toBeTruthy()
  })
})
```

`container.value(key, instance)` binds an object you built, which is the simplest way to fake a service. Config works the same way: `createTestApp({ config: { billing: { currency: 'eur' } } })`.

To test a provider's `wrap`, boot an app with it and render under `KitrProvider` from `kitr/react`:

```tsx
// app/providers/team_provider.test.tsx
import { KitrProvider } from 'kitr/react'
import { createTestApp } from 'kitr/testing'
import { render, screen } from '@testing-library/react'
import { expect, it } from 'vitest'
import teamProvider, { useTeam } from './team_provider'

it('puts the team in context', async () => {
  const app = await createTestApp({ providers: [teamProvider] })
  function TeamName() {
    return <p>{useTeam().team}</p>
  }
  render(
    <KitrProvider app={app}>
      <TeamName />
    </KitrProvider>,
  )
  expect(screen.getByText('acme')).toBeTruthy()
})
```

A component that calls `useApp` with nothing around it throws the `inside <KitrProvider>` error, which is what you want a test to catch:

```tsx
// app/components/environment-badge.test.tsx
import { render } from '@testing-library/react'
import { expect, it, vi } from 'vitest'
import { EnvironmentBadge } from './environment-badge'

it('needs the app in context', () => {
  vi.spyOn(console, 'error').mockImplementation(() => {})
  expect(() => render(<EnvironmentBadge />)).toThrow(/inside <KitrProvider>/)
})
```

## Next steps

- [API reference](/packages/react/api): every export of `kitr/react` with its signature.
- [Router](/packages/router): pages, loaders and guards, with `KitrProvider` already in place.
- [Testing](/packages/testing): `createTestApp`, `renderWithKitr` and the API test client.
- [Configuration](/docs/configuration): `kitrrc.ts`, `config/` and `app/env.ts`.
- [React documentation](https://react.dev): Suspense, context and error boundaries.


# Realtime API

Source: https://kitr.dev/packages/realtime/api

Every export of `kitr/realtime`, `kitr/realtime/client`, `kitr/realtime/server`, `kitr/realtime/socket.io`, `kitr/realtime/socket.io/server`, `kitr/realtime/sse`, `kitr/realtime/sse/server`, `kitr/realtime/react`, read from the published type definitions. The [guide](/packages/realtime) shows them in use.

## kitr/realtime

### channel

```ts
function channel<C extends ChannelDefinition<any, any>>(transport: SocketTransport, definition: C): ChannelHandle<C>;
```

Bind a channel definition to a transport. Events validated by their schema
(when given) are handed to `effects`, which `useSubscription` applies to the cache.

### createRealtimeClient

```ts
function createRealtimeClient(config?: RealtimeConfig): SocketTransport;
```

Creates the client transport `config/realtime.ts` names: websocket (default) or sse here; socket.io loads its
client from `kitr/realtime/socket.io` so the dependency stays optional.

```ts
let transport: SocketTransport | undefined
export const realtime = () => (transport ??= createRealtimeClient(realtimeConfig))
```
Call it lazily, as above, so nothing connects during SSR.

### createSocketClient

```ts
function createSocketClient(options: SocketClientOptions): SocketTransport;
```

The native WebSocket transport (partysocket underneath: reconnects, buffers
while offline). Subscriptions are re-sent after every reconnect.

### createSseTransport

```ts
function createSseTransport(options: SseTransportOptions): SocketTransport;
```

Server-Sent Events as a realtime transport: the server pushes over one `EventSource`,
the client subscribes and sends with plain `fetch` POSTs. Works through any HTTP host
and proxy, no upgrade needed. Same channels, same `useSubscription`.

### defineChannel

```ts
function defineChannel<TParams = void, const TData extends Record<string, unknown> = Record<string, unknown>>(definition: Omit<ChannelDefinition<TParams, any>, 'events'> & {
  events: {
    [K in keyof TData]: ChannelEvent<TData[K], TParams>;
  };
}): ChannelDefinition<TParams, {
  [K in keyof TData]: ChannelEvent<TData[K], TParams>;
}>;
```

One channel definition serves both ends: the client applies `effects` to the
cache, the server checks `authorize`. Switching WebSocket ⇄ Socket.IO is a config change.

```ts
export const projectChannel = defineChannel({
  name: 'projects',
  params: z.object({ id: z.string() }),
  events: {
    updated: { effects: (project, { id }) => ({ set: [{ key: ['projects', 'detail', id], data: project }] }) },
    deleted: { effects: () => ({ invalidate: [['projects', 'list']] }) },
  },
})
```
Import the same definition on the server (to serve and emit) and on the client (to subscribe).

### parseMessage

```ts
function parseMessage<T>(raw: unknown): T | null;
```

Parses a frame from a string, an ArrayBuffer or an object; returns `null` for anything that is not valid JSON.

### stableStringify

```ts
function stableStringify(value: unknown): string;
```

`JSON.stringify` with object keys sorted, so equal params always produce the same topic.

### topicFor

```ts
function topicFor(channel: string, params: unknown): string;
```

The topic string for a channel and params (`chat:{"room":"general"}`); key order in params does not matter.

### createWebSocketTransport

```ts
const createWebSocketTransport: typeof createSocketClient;
```

The native WebSocket transport (same as `createSocketClient`).

### defineConfig

```ts
const defineConfig: <const C extends RealtimeConfig>(config: C) => C;
```

Typed identity helper for `config/realtime.ts`.

### ChannelDefinition

```ts
interface ChannelDefinition<TParams = void, TEvents extends Record<string, ChannelEvent<any, TParams>> = Record<string, ChannelEvent<any, TParams>>> {
  /** Unique channel name; it is the first part of every topic and must match on both ends. */
  name: string;
  /** Schema for the subscription params. The server validates (and may transform) them before `authorize`. */
  params?: StandardSchemaV1<unknown, TParams>;
  /** The events this channel carries, by name. */
  events: TEvents;
  /** Server side: may this connection subscribe? `ctx` is what `authorize` on the server returned. */
  authorize?: (params: TParams, ctx: unknown) => boolean | Promise<boolean>;
  /** Server side: handle a client-sent message on this channel. */
  onMessage?: (event: string, data: unknown, params: TParams, ctx: unknown) => void | Promise<void>;
}
```

A channel as `defineChannel` returns it: its name, params schema, events and server-side hooks.

### ChannelEvent

```ts
interface ChannelEvent<TData = unknown, TParams = unknown> {
  /** Optional schema for the payload (validated on receive). */
  schema?: StandardSchemaV1<unknown, TData>;
  /**
   * What this event does to the query cache on the client. Method syntax on purpose: a channel
   * without a payload schema can still annotate `data` (`effects(message: Message) {...}`).
   */
  effects?(data: TData, params: TParams): CacheEffect | void;
}
```

One event a channel carries: an optional payload schema and the cache effects it applies on the client.

### ChannelHandle

```ts
interface ChannelHandle<C extends ChannelDefinition<any, any>> {
  /** A subscription contract for `useSubscription` (kitr/query) or `defineSubscription`. */
  subscription(): SubscriptionContract<ChannelParams<C>, ChannelEventUnion<C>>;
  /** Send a client event up the channel. */
  send<E extends keyof C['events'] & string>(params: ChannelParams<C>, event: E, data: unknown): void;
  /** The query key of a subscription: `['realtime', name, params]`. */
  key(params: ChannelParams<C>): QueryKey;
}
```

A channel bound to a transport, as `channel()` returns it.

### RealtimeConfig

```ts
interface RealtimeConfig {
  /** `websocket` (default, crossws/partysocket), `socket.io` (rooms, adapters) or `sse` (one-way events over HTTP, any host). */
  transport?: RealtimeTransport$1;
  /** Client URL. Default: same origin at `path`. */
  url?: string;
  /** Server path of the upgrade route (websocket), the SSE stream, or the Socket.IO path. Default `/ws`, `/events` for sse. */
  path?: string;
  /** Heartbeat interval in ms (client pings). Default 25 000; 0 disables. Not read by the built-in clients yet. */
  heartbeat?: number;
}
```

The shape of `config/realtime.ts`: which transport the client uses and where it connects.

### SocketClientOptions

```ts
interface SocketClientOptions {
  /** `ws://` or `wss://` URL, or a function (e.g. to append a token). */
  url: string | (() => string | Promise<string>);
  /** WebSocket subprotocols, passed to the WebSocket constructor. */
  protocols?: string | string[];
  /** Reconnect settings passed to partysocket. */
  reconnect?: {
    maxRetries?: number;
    minReconnectionDelay?: number;
    maxReconnectionDelay?: number;
  };
  /** Called for every server error that isn't tied to a subscription. */
  onError?: (error: KitrErrorShape) => void;
}
```

Options for `createSocketClient`, the native WebSocket transport.

### SocketTransport

```ts
interface SocketTransport {
  /** Subscribe to a channel topic. Returns a function that unsubscribes. */
  subscribe(channel: string, params: unknown, onEvent: (event: string, data: unknown) => void, onError?: (e: KitrErrorShape) => void): () => void;
  /** Send a client event up a channel; the server hands it to the channel's `onMessage`. */
  send(channel: string, params: unknown, event: string, data: unknown): void;
  /** Close the connection and stop reconnecting. */
  close(): void;
  /** The current connection state. */
  readonly status: SocketStatus;
  /** Listen for status changes. Returns a function that removes the listener. */
  onStatus(listener: (status: SocketStatus) => void): () => void;
}
```

What every realtime client implements: WebSocket, Socket.IO, SSE, or your own.
`channel()` and `useChannel()` only talk to this interface.

### SseTransportOptions

```ts
interface SseTransportOptions {
  /** The stream URL (`/events`). Control messages are POSTed to the same URL. */
  url: string | (() => string);
  /** Extra headers for control requests (the stream itself cannot carry headers; use cookies or a `?token=`). */
  headers?: Record<string, string> | (() => Record<string, string>);
  /** Called for server errors not tied to a subscription, and for failed control requests (`NETWORK`). */
  onError?: (error: KitrErrorShape) => void;
}
```

Options for `createSseTransport`, the Server-Sent Events client.

### ChannelEventUnion

```ts
type ChannelEventUnion<C extends ChannelDefinition<any, any>> = {
  [K in keyof C['events'] & string]: {
    event: K;
    data: EventData<C['events'][K]>;
  };
}[keyof C['events'] & string];
```

Every event of a channel as a `{ event, data }` union, which `useChannel` returns as `lastEvent`.

### ChannelParams

```ts
type ChannelParams<C> = C extends ChannelDefinition<infer P, any> ? P : never;
```

The params type a channel subscribes with.

### ClientMessage

```ts
type ClientMessage = {
  t: 'sub';
  id: string;
  ch: string;
  p: unknown;
} | {
  t: 'unsub';
  id: string;
} | {
  t: 'msg';
  ch: string;
  p: unknown;
  ev: string;
  d: unknown;
} | {
  t: 'ping';
};
```

A frame the client sends: subscribe (`sub`), unsubscribe (`unsub`), a client event (`msg`) or a `ping`.
The wire protocol shared by the WebSocket, Socket.IO and SSE transports.

### EventData

```ts
type EventData<E> = E extends ChannelEvent<infer D, any> ? D : never;
```

The payload type of one channel event, inferred from its `schema` or `effects` annotation.

### RealtimeStatus

```ts
type RealtimeStatus = SocketStatus;
```

Alias of `SocketStatus`.

### RealtimeTransport

```ts
type RealtimeTransport = SocketTransport;
```

Alias: the transport interface every realtime client implements.

### RealtimeTransportName

```ts
type RealtimeTransport$1 = 'websocket' | 'socket.io' | 'sse';
```

Which transport carries channel traffic: native WebSocket, Socket.IO, or Server-Sent Events.

### ServerMessage

```ts
type ServerMessage = {
  t: 'ev';
  ch: string;
  p: unknown;
  ev: string;
  d: unknown;
} | 
/** `p` is the params after the channel's schema ran; events are routed by them. */
{
  t: 'ok';
  id: string;
  p?: unknown;
} | {
  t: 'err';
  id?: string;
  e: KitrErrorShape;
} | {
  t: 'pong';
};
```

A frame the server sends: an event (`ev`), a subscription ack (`ok`), an error (`err`) or a `pong`.

### SocketStatus

```ts
type SocketStatus = 'connecting' | 'open' | 'closed';
```

The connection state a transport reports: connecting, open or closed.

## kitr/realtime/client

### channel

```ts
function channel<C extends ChannelDefinition<any, any>>(transport: SocketTransport, definition: C): ChannelHandle<C>;
```

Bind a channel definition to a transport. Events validated by their schema
(when given) are handed to `effects`, which `useSubscription` applies to the cache.

### createSocketClient

```ts
function createSocketClient(options: SocketClientOptions): SocketTransport;
```

The native WebSocket transport (partysocket underneath: reconnects, buffers
while offline). Subscriptions are re-sent after every reconnect.

### createWebSocketTransport

```ts
const createWebSocketTransport: typeof createSocketClient;
```

The native WebSocket transport (same as `createSocketClient`).

### ChannelHandle

```ts
interface ChannelHandle<C extends ChannelDefinition<any, any>> {
  /** A subscription contract for `useSubscription` (kitr/query) or `defineSubscription`. */
  subscription(): SubscriptionContract<ChannelParams<C>, ChannelEventUnion<C>>;
  /** Send a client event up the channel. */
  send<E extends keyof C['events'] & string>(params: ChannelParams<C>, event: E, data: unknown): void;
  /** The query key of a subscription: `['realtime', name, params]`. */
  key(params: ChannelParams<C>): QueryKey;
}
```

A channel bound to a transport, as `channel()` returns it.

### SocketClientOptions

```ts
interface SocketClientOptions {
  /** `ws://` or `wss://` URL, or a function (e.g. to append a token). */
  url: string | (() => string | Promise<string>);
  /** WebSocket subprotocols, passed to the WebSocket constructor. */
  protocols?: string | string[];
  /** Reconnect settings passed to partysocket. */
  reconnect?: {
    maxRetries?: number;
    minReconnectionDelay?: number;
    maxReconnectionDelay?: number;
  };
  /** Called for every server error that isn't tied to a subscription. */
  onError?: (error: KitrErrorShape) => void;
}
```

Options for `createSocketClient`, the native WebSocket transport.

### SocketTransport

```ts
interface SocketTransport {
  /** Subscribe to a channel topic. Returns a function that unsubscribes. */
  subscribe(channel: string, params: unknown, onEvent: (event: string, data: unknown) => void, onError?: (e: KitrErrorShape) => void): () => void;
  /** Send a client event up a channel; the server hands it to the channel's `onMessage`. */
  send(channel: string, params: unknown, event: string, data: unknown): void;
  /** Close the connection and stop reconnecting. */
  close(): void;
  /** The current connection state. */
  readonly status: SocketStatus;
  /** Listen for status changes. Returns a function that removes the listener. */
  onStatus(listener: (status: SocketStatus) => void): () => void;
}
```

What every realtime client implements: WebSocket, Socket.IO, SSE, or your own.
`channel()` and `useChannel()` only talk to this interface.

### RealtimeStatus

```ts
type RealtimeStatus = SocketStatus;
```

Alias of `SocketStatus`.

### RealtimeTransport

```ts
type RealtimeTransport = SocketTransport;
```

Alias: the transport interface every realtime client implements.

### SocketStatus

```ts
type SocketStatus = 'connecting' | 'open' | 'closed';
```

The connection state a transport reports: connecting, open or closed.

## kitr/realtime/server

### createSocketServer

```ts
function createSocketServer(options: SocketServerOptions): SocketServer;
```

Creates the native WebSocket server on crossws (via h3). Runs on Node, Bun, Deno and Cloudflare.
Attach it to a kitr server with `attach(server, path)`; emit with `use(channel, params).emit()`.

### realtimeProvider

```ts
function realtimeProvider(options: SocketServerOptions & {
  path?: string;
}): KitrProvider;
```

A provider that binds a WebSocket server as `realtime` in the container. It does not attach the
route: call `attach()` on the bound server yourself. `path` is accepted but not used.

### createRealtimeServer

```ts
const createRealtimeServer: typeof createSocketServer;
```

The WebSocket server factory under its transport-neutral name; same as `createSocketServer`.

### ChannelEmitter

```ts
interface ChannelEmitter<C extends ChannelDefinition<any, any>> {
  /** Send an event to every connection subscribed to this topic. A topic with no subscribers is a no-op. */
  emit<E extends keyof C['events'] & string>(event: E, data: C['events'][E] extends {
    schema: infer S;
  } ? S extends {
    '~standard': {
      types?: {
        output: infer O;
      };
    };
  } ? O : unknown : unknown): void;
  /** Subscriber count for this topic. */
  readonly size: number;
}
```

Publishes events to every subscriber of one channel topic, as `server.use(channel, params)` returns it.

### SocketServer

```ts
interface SocketServer {
  /** The h3 handler for the upgrade route: `server.h3.get('/ws', socket.handler)`. */
  handler: ReturnType<typeof defineWebSocketHandler>;
  /** Publish on a channel from an action, controller or job. */
  use<C extends ChannelDefinition<any, any>>(channel: C, params: ChannelParams<C>): ChannelEmitter<C>;
  /** Attach to a kitr server: registers the route and enables the upgrade. */
  attach(server: KitrServer, path?: string): SocketServer;
  /** Number of open connections. */
  readonly connections: number;
}
```

The realtime server for the native WebSocket transport, as `createRealtimeServer` returns it.

### SocketServerOptions

```ts
interface SocketServerOptions {
  /** Every channel clients may subscribe to. Subscribing to any other name fails with `NOT_FOUND`. */
  channels: ChannelDefinition<any, any>[];
  /** Authenticate the upgrade. Return per-connection context (e.g. the user) or throw/return false to reject. */
  authorize?: (request: Request) => unknown | Promise<unknown>;
}
```

Options for `createSocketServer`: the channels it serves and how it authenticates connections.

### RealtimeServer

```ts
type RealtimeServer = SocketServer;
```

Alias of `SocketServer`.

## kitr/realtime/socket.io

### channel

```ts
function channel<C extends ChannelDefinition<any, any>>(transport: SocketTransport, definition: C): ChannelHandle<C>;
```

Bind a channel definition to a transport. Events validated by their schema
(when given) are handed to `effects`, which `useSubscription` applies to the cache.

### createSocketIoClient

```ts
function createSocketIoClient(options?: SocketIoClientOptions): SocketTransport & {
  socket: Socket;
};
```

Creates the same `SocketTransport` as kitr/realtime, over Socket.IO; `.socket` is the raw socket.io-client socket. Use it with `channel()`
from kitr/realtime/socket.io; the channel definitions and `useSubscription` don't change.

### defineChannel

```ts
function defineChannel<TParams = void, const TData extends Record<string, unknown> = Record<string, unknown>>(definition: Omit<ChannelDefinition<TParams, any>, 'events'> & {
  events: {
    [K in keyof TData]: ChannelEvent<TData[K], TParams>;
  };
}): ChannelDefinition<TParams, {
  [K in keyof TData]: ChannelEvent<TData[K], TParams>;
}>;
```

One channel definition serves both ends: the client applies `effects` to the
cache, the server checks `authorize`. Switching WebSocket ⇄ Socket.IO is a config change.

```ts
export const projectChannel = defineChannel({
  name: 'projects',
  params: z.object({ id: z.string() }),
  events: {
    updated: { effects: (project, { id }) => ({ set: [{ key: ['projects', 'detail', id], data: project }] }) },
    deleted: { effects: () => ({ invalidate: [['projects', 'list']] }) },
  },
})
```
Import the same definition on the server (to serve and emit) and on the client (to subscribe).

### SocketIoClientOptions

```ts
interface SocketIoClientOptions extends Partial<ManagerOptions & SocketOptions> {
  /** Server URL. Default: the page's origin. */
  url?: string;
  /** Called for every server error that isn't tied to a subscription. */
  onError?: (error: KitrErrorShape) => void;
}
```

Options for `createSocketIoClient`: any socket.io-client option plus the server URL and an error handler.

## kitr/realtime/socket.io/server

### attachSocketIo

```ts
function attachSocketIo(io: Server, options: SocketIoServerOptions): SocketIoServer;
```

Serves kitr channels over an existing Socket.IO server. Rooms are channel topics, so the
Redis adapter and sticky sessions work as they do for any Socket.IO app.

```ts
const io = new Server(nodeServer)
const sockets = attachSocketIo(io, { channels: [projectChannel] })
sockets.use(projectChannel, { id }).emit('updated', project)
```
Connections are authenticated once in a namespace middleware; each subscription runs the channel's `authorize`.

### SocketIoServer

```ts
interface SocketIoServer {
  /** The Socket.IO server you passed in. */
  io: Server;
  /** Publish on a channel topic: `use(channel, params).emit(event, data)` emits to that topic's room. */
  use<C extends ChannelDefinition<any, any>>(channel: C, params: ChannelParams<C>): {
    emit(event: keyof C['events'] & string, data: unknown): void;
  };
}
```

Channels served over Socket.IO, as `attachSocketIo` returns them.

### SocketIoServerOptions

```ts
interface SocketIoServerOptions {
  /** Every channel clients may subscribe to. */
  channels: ChannelDefinition<any, any>[];
  /** Authenticate a connection (`socket.handshake.auth`). Return context or throw. */
  authorize?: (socket: Socket) => unknown | Promise<unknown>;
  /** Serve channels on this Socket.IO namespace instead of the default `/`. */
  namespace?: string;
}
```

Options for `attachSocketIo`: the channels to serve, connection auth and an optional namespace.

## kitr/realtime/sse

### createSseTransport

```ts
function createSseTransport(options: SseTransportOptions): SocketTransport;
```

Server-Sent Events as a realtime transport: the server pushes over one `EventSource`,
the client subscribes and sends with plain `fetch` POSTs. Works through any HTTP host
and proxy, no upgrade needed. Same channels, same `useSubscription`.

### SseTransportOptions

```ts
interface SseTransportOptions {
  /** The stream URL (`/events`). Control messages are POSTed to the same URL. */
  url: string | (() => string);
  /** Extra headers for control requests (the stream itself cannot carry headers; use cookies or a `?token=`). */
  headers?: Record<string, string> | (() => Record<string, string>);
  /** Called for server errors not tied to a subscription, and for failed control requests (`NETWORK`). */
  onError?: (error: KitrErrorShape) => void;
}
```

Options for `createSseTransport`, the Server-Sent Events client.

## kitr/realtime/sse/server

### createSseServer

```ts
function createSseServer(options: SseServerOptions): SseServer;
```

Realtime channels over Server-Sent Events: one streaming GET per client, control messages
over POST. Runs anywhere h3 runs, including hosts without WebSocket upgrades.

### sseProvider

```ts
function sseProvider(options: SseServerOptions): KitrProvider;
```

A provider that binds an SSE server as `realtime` in the container. It does not attach the route.

### SseServer

```ts
interface SseServer {
  /** GET opens the stream, POST carries sub/unsub/msg control messages. Mount both on one path. */
  handler: ReturnType<typeof defineHandler>;
  /** Publish on a channel from an action, controller or job. */
  use<C extends ChannelDefinition<any, any>>(channel: C, params: ChannelParams<C>): ChannelEmitter<C>;
  /** Register GET and POST on `path` (default `/events`) of a kitr server. */
  attach(server: KitrServer, path?: string): SseServer;
  /** Number of open streams. */
  readonly connections: number;
}
```

The realtime server for the SSE transport, as `createSseServer` returns it.

### SseServerOptions

```ts
interface SseServerOptions {
  /** Every channel clients may subscribe to. */
  channels: ChannelDefinition<any, any>[];
  /** Authenticate the stream request. Return per-connection context or throw/return false to reject. */
  authorize?: (request: Request) => unknown | Promise<unknown>;
  /** Keep-alive comment interval in ms. Default 20 000. */
  keepAlive?: number;
}
```

Options for `createSseServer`: the channels to serve, stream auth and the keep-alive interval.

## kitr/realtime/react

### useChannel

```ts
function useChannel<C extends ChannelDefinition<any, any>>(transport: SocketTransport, definition: C, params: ChannelParams<C>, options?: UseSubscriptionOptions<ChannelEventUnion<C>>): {
  status: "idle" | "open" | "error";
  lastEvent: ChannelEventUnion<C> | undefined;
  error: import("@kitr/core").KitrErrorShape | undefined;
};
```

Subscribe a component to a channel: `useChannel(realtime(), chatChannel, { room })`.
Events run the channel's cache `effects`; the hook also returns the last event and status.

### useRealtimeStatus

```ts
function useRealtimeStatus(transport: SocketTransport | undefined): SocketStatus;
```

`'connecting' | 'open' | 'closed'` for a connection indicator.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Realtime

Source: https://kitr.dev/packages/realtime

A chat, a notification bell, a project board that updates while you look at it: all of them need the server to push to screens that are already open. `kitr/realtime` lets you define a typed **channel** once, emit events on it from the server, and have every subscribed screen update its query cache. It runs over [crossws](https://crossws.unjs.io) WebSockets by default, or [Socket.IO](https://socket.io/docs/v4/) or Server-Sent Events, and the channel code stays the same on all three.

It runs on both sides: the server half (`kitr/realtime/server`) accepts connections and emits; the client half (`kitr/realtime`, `kitr/realtime/react`) subscribes. For one-off server calls that return a value, use [actions](/packages/actions) or [api](/packages/api) instead; realtime is for events the server sends when something changes.

This guide follows Acme's project board at `app.acme.com`. When Grace renames a project, Ada and Linus see the new name without reloading.

## Install

```sh
kitr add realtime
```

What `kitr add` does:

- Adds the [server](/packages/server) package first if the project does not have it yet.
- Installs `@kitr/realtime` and `crossws`. In a React app it also installs `partysocket`, the reconnecting WebSocket client.
- Adds `'@kitr/realtime'` to `packages` in `kitrrc.ts`. Realtime registers no provider.
- Writes `config/realtime.ts` (shown under Configure).
- Writes `app/channels/example.ts`, a sample channel named `example` with one `message` event.
- Writes `server/realtime.ts`, which creates the WebSocket server with `exampleChannel`.
- Adds `realtime.attach(server, '<path>')` to `server/main.ts` when that file exists, with the path from `config/realtime.ts`.
- In a React app, writes `app/realtime.ts`, which opens one client connection per tab on first use.
- Regenerates `config/index.ts`, the config list the standalone server imports.
- Adds a `## kitr: realtime` section to `AGENTS.md` that says where channels live, how the server emits and how components subscribe, and how to switch transports.

`kitr add realtime` asks no questions. It checks for React instead: a project without React (a pure backend) gets the `/ws` path and no client files. Pass `--dry-run` to print the changes without writing them:

```sh
kitr add realtime --dry-run
```

The `fullstack` and `server` kits and the `realtime` kit already include it. `kitr remove realtime` removes the package entry, the `AGENTS.md` section, `config/realtime.ts` and the `crossws`, `partysocket`, `socket.io` and `socket.io-client` dependencies. It leaves `app/channels/`, `server/realtime.ts`, `app/realtime.ts` and the `attach` line in `server/main.ts`, because you have likely edited them.

## Configure

In a React app, `kitr add realtime` writes this file:

```ts
// config/realtime.ts
import { defineConfig } from 'kitr/realtime'

export default defineConfig({
  // websocket (default), socket.io or sse: the channels and hooks stay the same.
  transport: 'websocket',
  path: '/api/ws',
})
```

In a project without React, the path is `'/ws'` instead of `'/api/ws'`.

The client reads this file through `createRealtimeClient(config)`. The server does not read it: `server/realtime.ts` decides which server to create, and `server/main.ts` passes the path to `attach`. Keep the two in step when you change either.

| Option | Default | Description |
| --- | --- | --- |
| `transport` | `'websocket'` | `'websocket'` (crossws and partysocket), `'socket.io'` (rooms, adapters) or `'sse'` (one-way stream over HTTP, control messages over POST). |
| `path` | `'/ws'`, or `'/events'` for `sse` | Where the server listens. The client connects to the same origin at this path. |
| `url` | same origin at `path` | A full URL for the client, such as `wss://realtime.acme.com/ws`, when the realtime server is on another host. |
| `heartbeat` | `25000` | Declared for a client ping interval in milliseconds. The built-in clients do not read it yet. |

Realtime adds no environment variables.

## Push your first update

Three files make a live project name: a channel both ends import, an emit on the server, and a subscription in a component.

Define the channel. `zod` is used for schemas here (`pnpm add zod`); any [Standard Schema](https://standardschema.dev) library works.

```ts
// app/channels/projects.ts
import { defineChannel } from 'kitr/realtime'
import { z } from 'zod'

export const projectSchema = z.object({ id: z.string(), name: z.string(), teamId: z.string() })
export type Project = z.infer<typeof projectSchema>

export const projectChannel = defineChannel({
  name: 'projects',
  params: z.object({ id: z.string() }),
  events: {
    updated: {
      schema: projectSchema,
      effects: (project, { id }) => ({ set: [{ key: ['projects', 'detail', id], data: project }] }),
    },
  },
})
```

Add the channel to the server in `server/realtime.ts`, then emit from the controller that renames a project:

```ts
// server/realtime.ts
import { createRealtimeServer } from 'kitr/realtime/server'
import { projectChannel } from '#app/channels/projects'

export const realtime = createRealtimeServer({
  channels: [projectChannel],
})
```

```ts
// server/controllers/projects_controller.ts
import type { HttpContext } from 'kitr/api'
import { type Project, projectChannel } from '#app/channels/projects'
import { realtime } from '#server/realtime'

export default class ProjectsController {
  async update({ params, body }: HttpContext<{ id: string }, Record<string, string>, { name: string }>) {
    const project: Project = { id: params.id, name: body.name, teamId: 'team_acme' }
    // ... save it with your database
    realtime.use(projectChannel, { id: params.id }).emit('updated', project)
    return project
  }
}
```

Subscribe in the component that shows the project:

```tsx
// app/features/projects/project-title.tsx
import { useQuery } from 'kitr/query'
import { useChannel } from 'kitr/realtime/react'
import { type Project, projectChannel } from '#app/channels/projects'
import { realtime } from '#app/realtime'

export function ProjectTitle({ id }: { id: string }) {
  useChannel(realtime(), projectChannel, { id })
  const { data } = useQuery<Project>({ queryKey: ['projects', 'detail', id], enabled: false })
  return <h1>{data?.name ?? 'Loading'}</h1>
}
```

When Grace saves "Apollo launch", the server sends one `updated` event to every connection subscribed to `projects` with `{ id: 'prj_1' }`. Each client validates the payload against `projectSchema` and runs `effects`, which writes the project into the `['projects', 'detail', 'prj_1']` cache entry. Ada's and Linus's headings re-render with the new name. No refetch happens.

## Define a channel

A channel is a name, the params a subscriber picks, and the events the server sends. One file under `app/channels/` is imported by both ends, so the event names and payload types cannot drift.

```ts
// app/channels/projects.ts
import { defineChannel } from 'kitr/realtime'
import { z } from 'zod'

export const projectSchema = z.object({ id: z.string(), name: z.string(), teamId: z.string() })

export const projectChannel = defineChannel({
  name: 'projects',
  params: z.object({ id: z.string().trim() }),
  events: {
    updated: { schema: projectSchema },
    deleted: {},
    typing: { schema: z.object({ user: z.string() }) },
  },
})
```

| Field | Runs on | Description |
| --- | --- | --- |
| `name` | both | Unique channel name. Two channels with the same name collide. |
| `params` | server | Schema for what a client subscribes with. Invalid params fail with `VALIDATION`. |
| `events` | both | Event names, each with an optional `schema` and `effects`. |
| `authorize(params, ctx)` | server | Return `false` to refuse a subscription. See Authorize a subscription. |
| `onMessage(event, data, params, ctx)` | server | Receives events a client sends up the channel. |

`kitr make:channel <name>` writes a starting file (see Commands). Without a `params` schema, give the params type as a type argument: `defineChannel<{ room: string }>({ ... })`.

## Validate params and payloads

On the server, `params` runs before anything else. Its output, not the raw input, is what the subscription is filed under. A schema that trims or lowercases therefore merges `' prj_1 '` and `'prj_1'` into one topic.

On the client, an event with a `schema` is validated before `effects` runs. A payload that fails is not applied; the subscription's error handler gets a `VALIDATION` error instead:

```ts
// app/features/projects/project-errors.ts
import { channel } from 'kitr/realtime'
import { projectChannel } from '#app/channels/projects'
import { realtime } from '#app/realtime'

channel(realtime(), projectChannel)
  .subscription()
  .subscribe(
    { id: 'prj_1' },
    {
      next: (event) => console.log(event.event, event.data),
      error: (error) => console.warn(error),
      // => { code: 'VALIDATION', message: 'Invalid payload for projects.updated', status: 422, fieldErrors: { name: [...] } }
    },
  )
```

Events the channel does not declare are dropped on the client without an error.

> **Warning**
> The server does not validate what you pass to `emit`. Payload schemas protect clients from a malformed event; they do not stop the server from sending one. Emit data you built from your own records.

## Update the cache from events

`effects(data, params)` returns the same cache effect a [query](/packages/query) mutation returns: `set` writes an entry, `invalidate` marks entries stale so mounted queries refetch, `remove` drops them.

```ts
// app/channels/projects.ts
import { defineChannel } from 'kitr/realtime'
import { z } from 'zod'

const projectSchema = z.object({ id: z.string(), name: z.string(), teamId: z.string() })

export const projectChannel = defineChannel({
  name: 'projects',
  params: z.object({ id: z.string() }),
  events: {
    // Write the new value: no request.
    updated: {
      schema: projectSchema,
      effects: (project, { id }) => ({
        set: [{ key: ['projects', 'detail', id], data: project }],
        invalidate: [['projects', 'list']],
      }),
    },
    // Drop the detail and refetch every list.
    deleted: {
      effects: (_data, { id }) => ({
        remove: [['projects', 'detail', id]],
        invalidate: [['projects', 'list']],
      }),
    },
  },
})
```

Use `set` when the event carries the full record. Use `invalidate` when it only says something changed; the query refetches through its normal `fetch`, so permission checks and joins stay on the server. Don't call `queryClient.setQueryData` in a component for socket events; declare it in `effects` so every subscriber behaves the same.

## Emit from the server

On the server, `realtime.use(channel, params)` returns an emitter for one topic. Import `realtime` from `server/realtime.ts` in a controller, an action or a job:

```ts
// app/actions/projects/rename.ts
import { defineAction } from 'kitr/actions'
import { z } from 'zod'
import { projectChannel } from '#app/channels/projects'
import { realtime } from '#server/realtime'

export const renameProject = defineAction('projects.rename', {
  input: z.object({ id: z.string(), name: z.string().min(2) }),
  handler: async ({ input }) => {
    const project = { id: input.id, name: input.name, teamId: 'team_acme' }
    // ... save it with your database
    realtime.use(projectChannel, { id: input.id }).emit('updated', project)
    return project
  },
})
```

The emitter also reports how many connections are listening, which helps you skip expensive work nobody will see:

```ts
// server/jobs/project_stats.ts
import { projectChannel } from '#app/channels/projects'
import { realtime } from '#server/realtime'

const topic = realtime.use(projectChannel, { id: 'prj_1' })
console.log(topic.size)
// => 2 (Ada and Linus have the board open)
console.log(realtime.connections)
// => 3 (open WebSocket connections, subscribed or not)
```

Emit with the params as the server normalised them. With `z.string().trim()` above, `use(projectChannel, { id: 'prj_1' })` reaches a client that subscribed with `' prj_1 '`; `use(projectChannel, { id: ' prj_1 ' })` reaches nobody. Key order in params does not matter: `{ a: 1, b: 2 }` and `{ b: 2, a: 1 }` are the same topic.

## Subscribe in a component

In a component, `useChannel(transport, channel, params, options?)` from `kitr/realtime/react` subscribes on mount, applies each event's `effects` to the query cache, and unsubscribes on unmount. It needs the [query](/packages/query) provider, which every kit with React includes.

```tsx
// app/features/projects/project-board.tsx
import { useChannel } from 'kitr/realtime/react'
import { projectChannel } from '#app/channels/projects'
import { realtime } from '#app/realtime'

export function ProjectBoard({ id }: { id: string }) {
  const live = useChannel(realtime(), projectChannel, { id }, {
    onEvent: (event) => {
      if (event.event === 'deleted') window.location.assign('/projects')
    },
    onError: (error) => console.warn(error.code, error.message),
  })
  return <p>{live.status === 'open' ? 'Live' : live.status}</p>
}
```

`useChannel` returns `{ status, lastEvent, error }`:

| Field | Description |
| --- | --- |
| `status` | `'idle'` before subscribing or with `enabled: false`, `'open'` once subscribed, `'error'` after an error. |
| `lastEvent` | The last `{ event, data }` received, typed as a union of the channel's events. |
| `error` | The last error, a `KitrErrorShape` such as `{ code: 'FORBIDDEN', ... }`. |

| Option | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | `false` skips the subscription, for example until a project id is known. |
| `onEvent(event)` | none | Runs for every valid event, after `effects`. |
| `onError(error)` | none | Runs for subscription errors: params, authorization, payload validation. |

Changing `params` resubscribes. `app/realtime.ts` opens the connection the first time `realtime()` runs, so render subscribing components in the browser only: a route with `ssrRoute(false)` from [seo](/packages/seo), or a component that mounts after hydration.

## Subscribe with useSubscription

`channel(transport, definition)` binds a channel to a transport. Its `subscription()` is a kitr subscription contract, so `useSubscription` and `defineSubscription` from [query](/packages/query) take it directly. Use this when your queries file already holds the other contracts for a feature:

```ts
// app/features/projects/queries.ts
import { defineSubscription } from 'kitr/query'
import { channel } from 'kitr/realtime'
import { projectChannel } from '#app/channels/projects'
import { realtime } from '#app/realtime'

/** Call inside a component, so the socket opens in the browser. */
export const projectSubscription = () =>
  defineSubscription(channel(realtime(), projectChannel).subscription())
```

```tsx
// app/features/projects/project-live.tsx
import { useSubscription } from 'kitr/query'
import { useMemo } from 'react'
import { projectSubscription } from './queries'

export function ProjectLive({ id }: { id: string }) {
  const subscription = useMemo(() => projectSubscription(), [])
  const live = useSubscription(subscription, { id })
  return <span>{live.status}</span>
}
```

The handle's `key(params)` is `['realtime', 'projects', { id: 'prj_1' }]`. It names the subscription; events still write to the keys your `effects` return.

## Show the connection status

`useChannel` reports the subscription. To show whether the socket itself is connected, use `useRealtimeStatus(transport)`:

```tsx
// app/components/connection-badge.tsx
import { useRealtimeStatus } from 'kitr/realtime/react'
import { realtime } from '#app/realtime'

export function ConnectionBadge() {
  const status = useRealtimeStatus(realtime())
  // => 'connecting' | 'open' | 'closed'
  return <span>{status === 'open' ? 'Online' : 'Reconnecting'}</span>
}
```

The WebSocket client reconnects on its own with backoff and sends every subscription again after it reconnects. Events emitted while a client was offline are not replayed, so pair live events with queries: on reconnect, invalidate what matters, or let `refetchOnWindowFocus` catch up.

## Send events from the client

A client can send an event up a channel with `channel(...).send(params, event, data)`. The server runs the channel's `params` schema and `authorize`, then calls the channel's `onMessage`. Here, typing in a project's comment box tells everyone else on the board.

The channel declares the `typing` event, so clients can receive it:

```ts
// app/channels/projects.ts
import { defineChannel } from 'kitr/realtime'
import { z } from 'zod'

export const projectChannel = defineChannel({
  name: 'projects',
  params: z.object({ id: z.string() }),
  events: {
    typing: { schema: z.object({ user: z.string() }) },
  },
})
```

The server adds `onMessage` to its copy of the channel. The server matches channels by `name`, so the client keeps importing the shared file and the handler never reaches the browser:

```ts
// server/realtime.ts
import { createRealtimeServer } from 'kitr/realtime/server'
import { projectChannel } from '#app/channels/projects'

export const realtime = createRealtimeServer({
  channels: [
    {
      ...projectChannel,
      onMessage: (event, data, params) => {
        if (event !== 'typing' || typeof (data as { user?: unknown })?.user !== 'string') return
        realtime.use(projectChannel, params as { id: string }).emit('typing', data as { user: string })
      },
    },
  ],
})
```

```tsx
// app/features/projects/comment-box.tsx
import { channel } from 'kitr/realtime'
import { projectChannel } from '#app/channels/projects'
import { realtime } from '#app/realtime'

export function CommentBox({ projectId }: { projectId: string }) {
  const project = channel(realtime(), projectChannel)
  return <textarea onKeyDown={() => project.send({ id: projectId }, 'typing', { user: 'Ada' })} />
}
```

`onMessage(event, data, params, ctx)` receives the validated params and the connection's context. Check `data` yourself, as above: event schemas are checked when events arrive at a client, not at the server. For anything that changes data, call an action or an API route instead; `send` has no reply and no retry.

## Authenticate connections

On the server, `authorize(request)` runs once, when a connection opens. Return the connection's context, such as the signed-in user. Return `false` and the upgrade is refused with `401 Unauthorized`. Throw a `KitrError` to refuse with its status; any other thrown error becomes a 401.

```ts
// server/realtime.ts
import { KitrError } from 'kitr/app'
import { createRealtimeServer } from 'kitr/realtime/server'
import { projectChannel } from '#app/channels/projects'
import { userFromSession } from '#server/auth'

export const realtime = createRealtimeServer({
  channels: [projectChannel],
  authorize: async (request) => {
    const cookie = request.headers.get('cookie') ?? ''
    const session = cookie.match(/(?:^|;\s*)acme_session=([^;]+)/)?.[1]
    const user = session ? await userFromSession(session) : null
    if (!user) throw KitrError.unauthorized()
    return { user }
  },
})
```

`userFromSession` stands for your own lookup. Browsers send cookies with the WebSocket upgrade for the same site, so a session cookie works without extra client code. For a token, put it in the URL from the client and read it with `new URL(request.url).searchParams.get('token')`:

```ts
// app/realtime.ts
import { createSocketClient, type SocketTransport } from 'kitr/realtime'
import realtimeConfig from '#config/realtime'

let transport: SocketTransport | undefined

export function realtime(): SocketTransport {
  transport ??= createSocketClient({
    url: async () => {
      const token = localStorage.getItem('acme_token') ?? ''
      return `${window.location.origin.replace(/^http/, 'ws')}${realtimeConfig.path}?token=${token}`
    },
  })
  return transport
}
```

The `url` function runs again on every reconnect, so a refreshed token is picked up.

## Authorize a subscription

`authorize(params, ctx)` on the channel decides who may subscribe to which topic. `ctx` is what the server's `authorize(request)` returned. It also guards `send`.

```ts
// app/channels/projects.ts
import { defineChannel } from 'kitr/realtime'
import { z } from 'zod'

type Ctx = { user: { id: string; teamIds: string[] } }

export const projectChannel = defineChannel({
  name: 'projects',
  params: z.object({ id: z.string(), teamId: z.string() }),
  events: { updated: {} },
  authorize: ({ teamId }, ctx) => (ctx as Ctx).user.teamIds.includes(teamId),
})
```

When Linus, who is not on `team_acme`, subscribes with `{ id: 'prj_1', teamId: 'team_acme' }`, his `useChannel` gets `error: { code: 'FORBIDDEN', message: 'Not allowed on channel "projects"', status: 403 }` and receives no events. A channel without `authorize` lets every authenticated connection subscribe.

## Handle errors

Errors reach the most specific handler. Subscription errors (bad params, `FORBIDDEN`, an unknown channel name) go to that subscription's `onError`. Errors with no subscription, such as a `send` on an unknown channel, go to the transport's `onError`:

```ts
// app/realtime.ts
import { createSocketClient, type SocketTransport } from 'kitr/realtime'
import realtimeConfig from '#config/realtime'

let transport: SocketTransport | undefined

export function realtime(): SocketTransport {
  transport ??= createSocketClient({
    url: () => `${window.location.origin.replace(/^http/, 'ws')}${realtimeConfig.path}`,
    reconnect: { maxRetries: 20, minReconnectionDelay: 1_000, maxReconnectionDelay: 30_000 },
    onError: (error) => console.warn('[realtime]', error.code, error.message),
  })
  return transport
}
```

This is the same file `kitr add` writes, with `createSocketClient` called directly so you can pass the options it takes:

| Option | Default | Description |
| --- | --- | --- |
| `url` | required | `ws://` or `wss://` URL, or a function returning one (sync or async). |
| `protocols` | none | WebSocket subprotocols. |
| `reconnect.maxRetries` | partysocket's default | Give up after this many attempts. |
| `reconnect.minReconnectionDelay` | partysocket's default | First retry delay in milliseconds. |
| `reconnect.maxReconnectionDelay` | partysocket's default | Longest retry delay in milliseconds. |
| `onError(error)` | none | Server errors not tied to a subscription. |

See [partysocket](https://docs.partykit.io/reference/partysocket-api/) for the reconnect defaults.

## Connect from another origin

When the realtime server runs on its own host, set `url` in config. The client uses it as is, instead of the page's origin plus `path`:

```ts
// config/realtime.ts
import { defineConfig } from 'kitr/realtime'

export default defineConfig({
  transport: 'websocket',
  path: '/ws',
  url: 'wss://realtime.acme.com/ws',
})
```

From a Node script or a test, there is no page origin. Call `createSocketClient` with a full URL; Node 22 and later ship a global `WebSocket`:

```ts
// scripts/watch_project.ts
import { channel, createSocketClient } from 'kitr/realtime'
import { projectChannel } from '#app/channels/projects'

const transport = createSocketClient({ url: 'ws://localhost:3001/ws' })
channel(transport, projectChannel)
  .subscription()
  .subscribe({ id: 'prj_1' }, { next: (event) => console.log(event) })
// => { event: 'updated', data: { id: 'prj_1', name: 'Apollo launch', teamId: 'team_acme' } }
```

## Bind the server in the container

`server/realtime.ts` exports one module-level server, which is all most apps need. To reach it through the app container instead, as `ctx.app.container.use('realtime')`, register `realtimeProvider` and attach the bound server after boot:

```ts
// server/main.ts
import { mountRoutes } from 'kitr/api'
import { realtimeProvider } from 'kitr/realtime/server'
import { createServer } from 'kitr/server'
import { projectChannel } from '#app/channels/projects'
import { config } from '../config'
import rc from '../kitrrc'
import { routes } from './routes'

export const server = createServer({
  providers: [...rc.providers, realtimeProvider({ channels: [projectChannel] })],
  config,
})
mountRoutes(server, routes)
await server.boot()
server.app.container.use('realtime').attach(server, '/ws')
```

```ts
// server/controllers/projects_controller.ts
import type { HttpContext } from 'kitr/api'
import { projectChannel } from '#app/channels/projects'

export default class ProjectsController {
  async destroy({ app, params }: HttpContext<{ id: string }>) {
    app.container.use('realtime').use(projectChannel, { id: params.id }).emit('deleted', null)
    return { ok: true }
  }
}
```

The provider only binds the server; it does not register the route, and its `path` option is not used. `attach` must run before `server.listen()`, because it turns on WebSocket support for the listener. For SSE, `sseProvider` from `kitr/realtime/sse/server` does the same.

## Transports

All three transports implement one client interface and share the wire protocol, so channels, `effects`, `useChannel` and `emit` are identical. What changes is the server object in `server/realtime.ts`, its `attach` call, and the client the app creates.

| `transport` | Client | Server | Use it when |
| --- | --- | --- | --- |
| `websocket` | `createSocketClient` (partysocket) | `createRealtimeServer` (crossws via h3) | The default. Two-way, low latency, runs on Node, Bun, Deno and Cloudflare. |
| `socket.io` | `createSocketIoClient` | `attachSocketIo` | You need several server instances (Redis adapter) or already run Socket.IO. |
| `sse` | `createSseTransport` (EventSource plus POST) | `createSseServer` | Your host or proxy does not allow WebSocket upgrades. |

### WebSocket

The default. `kitr add realtime` sets it up: `crossws` on the server, `partysocket` in the browser.

```ts
// server/realtime.ts
import { createRealtimeServer } from 'kitr/realtime/server'
import { projectChannel } from '#app/channels/projects'

export const realtime = createRealtimeServer({ channels: [projectChannel] })
```

```ts
// server/main.ts
import { mountRoutes } from 'kitr/api'
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'
import { realtime } from './realtime'
import { routes } from './routes'

export const server = createServer({ providers: rc.providers, config })
mountRoutes(server, routes)
// WebSocket upgrades on /api/ws, next to the routes.
realtime.attach(server, '/api/ws')
```

`attach(server, path)` registers the upgrade route on the server's h3 app and turns on `websocket` for `server.listen()`. Without `crossws` installed, `listen()` throws `[kitr/server] websocket: true needs the crossws package. Run kitr add socket.` See the [crossws docs](https://crossws.unjs.io) for runtime adapters.

### Socket.IO

Install both halves:

```sh
pnpm add socket.io socket.io-client
```

Set the transport and path in config:

```ts
// config/realtime.ts
import { defineConfig } from 'kitr/realtime'

export default defineConfig({
  transport: 'socket.io',
  path: '/api/socket.io',
})
```

On the server, create a Socket.IO server and serve your channels on it with `attachSocketIo`. Its `authorize` receives the socket and reads `socket.handshake.auth`:

```ts
// server/realtime.ts
import { KitrError } from 'kitr/app'
import { attachSocketIo } from 'kitr/realtime/socket.io/server'
import { Server } from 'socket.io'
import { projectChannel } from '#app/channels/projects'
import { userFromToken } from '#server/auth'

export const io = new Server({ path: '/api/socket.io' })

export const realtime = attachSocketIo(io, {
  channels: [projectChannel],
  authorize: async (socket) => {
    const user = await userFromToken(String(socket.handshake.auth.token ?? ''))
    if (!user) throw KitrError.unauthorized()
    return { user }
  },
})
```

Bind it to the HTTP server once the kitr server is listening:

```ts
// server/main.ts
import type { Server as HttpServer } from 'node:http'
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'
import { io } from './realtime'

export const server = createServer({ providers: rc.providers, config })
const listening = await server.listen({ port: 3001 })
io.attach(listening.node as HttpServer)
```

In the browser, `createRealtimeClient` refuses `socket.io` so that `socket.io-client` stays out of bundles that don't use it. Create the client from `kitr/realtime/socket.io`, which also exports `channel` and `defineChannel`:

```ts
// app/realtime.ts
import type { SocketTransport } from 'kitr/realtime'
import { createSocketIoClient } from 'kitr/realtime/socket.io'
import realtimeConfig from '#config/realtime'

let transport: SocketTransport | undefined

export function realtime(): SocketTransport {
  transport ??= createSocketIoClient({
    path: realtimeConfig.path,
    auth: { token: localStorage.getItem('acme_token') ?? '' },
  })
  return transport
}
```

`createSocketIoClient` takes every [socket.io-client option](https://socket.io/docs/v4/client-options/) plus `url` and `onError`, and exposes the raw socket as `.socket`. Each channel topic is a Socket.IO room, so `realtime.use(channel, params).emit()` emits to that room. Pass `namespace: '/board'` to `attachSocketIo` to serve channels on a namespace. The Socket.IO emitter has no `size`.

### Server-Sent Events

SSE needs no extra packages. The server streams events over one long `GET`; the client subscribes and sends with `POST`s to the same path.

```ts
// config/realtime.ts
import { defineConfig } from 'kitr/realtime'

export default defineConfig({
  transport: 'sse',
  path: '/api/events',
})
```

```ts
// server/realtime.ts
import { createSseServer } from 'kitr/realtime/sse/server'
import { projectChannel } from '#app/channels/projects'

export const realtime = createSseServer({
  channels: [projectChannel],
  keepAlive: 15_000,
})
```

```ts
// server/main.ts
import { mountRoutes } from 'kitr/api'
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'
import { realtime } from './realtime'
import { routes } from './routes'

export const server = createServer({ providers: rc.providers, config })
mountRoutes(server, routes)
realtime.attach(server, '/api/events')
```

The `app/realtime.ts` that `kitr add` wrote already works: `createRealtimeClient` returns `createSseTransport({ url: config.url ?? config.path })` for `sse`. To pass headers on the control `POST`s, create the transport yourself:

```ts
// app/realtime.ts
import { createSseTransport, type SocketTransport } from 'kitr/realtime'

let transport: SocketTransport | undefined

export function realtime(): SocketTransport {
  transport ??= createSseTransport({
    url: '/api/events',
    headers: () => ({ 'x-acme-team': 'team_acme' }),
  })
  return transport
}
```

| Option | Default | Description |
| --- | --- | --- |
| `keepAlive` (server) | `20000` | Milliseconds between keep-alive comments, so proxies don't close an idle stream. |
| `authorize(request)` (server) | none | Runs when the stream opens. Same rules as the WebSocket server. |
| `url` (client) | required | The stream URL. Control messages are POSTed to it. |
| `headers` (client) | none | Headers for the control `POST`s, or a function returning them. |
| `onError` (client) | none | Errors without a subscription, and failed `POST`s as `NETWORK`. |

`EventSource` cannot set headers, so the stream authenticates by cookie (it is opened with credentials) or by a `?token=` in the URL. With SSE, subscribe with params already in the form the `params` schema outputs: the SSE server does not send normalised params back, so a subscription with `' prj_1 '` receives nothing. See [MDN on Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events).

## Run more than one server instance

Each server keeps its subscriptions in memory. With two instances behind a load balancer, an `emit` on instance A reaches only the clients connected to A.

> **Warning**
> With the WebSocket or SSE transport and several instances, clients on other instances silently miss events. Run one realtime instance, or use Socket.IO with an adapter.

With Socket.IO, add the [Redis adapter](https://socket.io/docs/v4/redis-adapter/) and every instance's emits reach every room:

```ts
// server/realtime.ts
import { createAdapter } from '@socket.io/redis-adapter'
import { attachSocketIo } from 'kitr/realtime/socket.io/server'
import { createClient } from 'redis'
import { Server } from 'socket.io'
import { projectChannel } from '#app/channels/projects'

const pub = createClient({ url: process.env.REDIS_URL })
const sub = pub.duplicate()
await Promise.all([pub.connect(), sub.connect()])

export const io = new Server({ path: '/api/socket.io', adapter: createAdapter(pub, sub) })
export const realtime = attachSocketIo(io, { channels: [projectChannel] })
```

Socket.IO also needs sticky sessions at the load balancer unless clients use only the `websocket` transport (`transports: ['websocket']` on the client).

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:channel <name>` | Writes `app/channels/<name>.ts` with `defineChannel`, a `zod` params schema, `updated` and `deleted` events and an open `authorize`. |

```sh
kitr make:channel invoices
```

```ts
// app/channels/invoices.ts
import { defineChannel } from 'kitr/realtime'
import { z } from 'zod'

export const invoicesChannel = defineChannel({
  name: 'invoices',
  params: z.object({ id: z.string() }),
  events: {
    updated: {
      effects: (data: unknown, { id }) => ({ set: [{ key: ['invoices', 'detail', id], data }] }),
    },
    deleted: {
      effects: () => ({ invalidate: [['invoices', 'list']] }),
    },
  },
  authorize: () => true,
})
```

The file name is the snake-case form of the name. Add the new channel to `channels` in `server/realtime.ts`; a client that subscribes to a channel the server does not list gets `NOT_FOUND`.

## Errors

Errors travel as kitr error shapes (`{ code, message, status }`) to the subscription's `onError`, or to the transport's `onError` when there is no subscription.

| Code | When | What to do |
| --- | --- | --- |
| `NOT_FOUND` | `Channel "invoices" not found`: the channel is not in the server's `channels`. | Add it to `createRealtimeServer({ channels })`. |
| `VALIDATION` (server) | The subscription params fail the channel's `params` schema. `fieldErrors` says which field. | Fix the params the component passes. |
| `VALIDATION` (client) | `Invalid payload for projects.updated`: an emitted payload fails the event `schema`. | Fix the data the server emits. |
| `FORBIDDEN` | The channel's `authorize` returned `false`: `Not allowed on channel "projects"`. | Expected for users without access; show a message. |
| HTTP `401` | The server's `authorize(request)` returned `false` or threw. The connection never opens. | Sign in, or send the cookie or token. |
| HTTP `410` | SSE only: a control `POST` named a connection the server no longer has. | The client reconnects and resubscribes on its own. |
| `NETWORK` | SSE only: a control `POST` failed. | Check the network; the subscription is not active. |
| `[kitr/realtime] transport "socket.io": create the client with createSocketIoClient() from kitr/realtime/socket.io` | `createRealtimeClient` with `transport: 'socket.io'`. | Use `createSocketIoClient` in `app/realtime.ts`. |

## Testing

Server and client both run in Node, so a test can start the real server on a free port and subscribe with the real client. This checks the channel, the authorization and the emit together:

```ts
// test/project_channel.test.ts
import { channel, createSocketClient, type SocketTransport } from 'kitr/realtime'
import { createRealtimeServer } from 'kitr/realtime/server'
import { silentLogger } from 'kitr/logger'
import { createServer } from 'kitr/server'
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
import { projectChannel } from '#app/channels/projects'

describe('projects channel', () => {
  const server = createServer({ logger: silentLogger })
  const realtime = createRealtimeServer({
    channels: [projectChannel],
    authorize: (request) => ({ user: new URL(request.url).searchParams.get('user') }),
  })
  realtime.attach(server, '/ws')
  let base = ''
  let close: () => Promise<void>
  let client: SocketTransport

  beforeAll(async () => {
    const listening = await server.listen({ port: 0, host: '127.0.0.1' })
    base = listening.url.replace(/^http/, 'ws')
    close = listening.close
  })
  afterAll(async () => {
    client?.close()
    await close()
  })

  it('delivers updated projects to subscribers', async () => {
    client = createSocketClient({ url: `${base}/ws?user=ada`, reconnect: { maxRetries: 0 } })
    const events: unknown[] = []
    channel(client, projectChannel)
      .subscription()
      .subscribe({ id: 'prj_1' }, { next: (event) => events.push(event) })

    await vi.waitFor(() => expect(realtime.use(projectChannel, { id: 'prj_1' }).size).toBe(1))
    realtime
      .use(projectChannel, { id: 'prj_1' })
      .emit('updated', { id: 'prj_1', name: 'Apollo launch', teamId: 'team_acme' })

    await vi.waitFor(() =>
      expect(events).toEqual([
        { event: 'updated', data: { id: 'prj_1', name: 'Apollo launch', teamId: 'team_acme' } },
      ]),
    )
  })
})
```

`port: 0` picks a free port, and `vi.waitFor` retries until the subscription has reached the server. The test uses the channel from "Push your first update".

To test what the cache looks like after an event, call the subscription's `effects` directly. It is a plain function:

```ts
// test/project_effects.test.ts
import { channel, type SocketTransport } from 'kitr/realtime'
import { expect, it } from 'vitest'
import { projectChannel } from '#app/channels/projects'

it('writes the project detail', () => {
  const idle = { subscribe: () => () => {} } as unknown as SocketTransport
  const effects = channel(idle, projectChannel).subscription().effects!
  const project = { id: 'prj_1', name: 'Apollo launch', teamId: 'team_acme' }
  expect(effects({ event: 'updated', data: project }, { id: 'prj_1' })).toEqual({
    set: [{ key: ['projects', 'detail', 'prj_1'], data: project }],
  })
})
```

For component tests, pass a memory transport (see Extend) instead of `realtime()`, render with `renderWithKitr` from [testing](/packages/testing), and push events from the test.

## Extend

Every client is a `SocketTransport`. Implement it to put channels on another service, such as a hosted pub/sub, or to drive components from a test. This one keeps subscriptions in memory and lets the caller push events:

```ts
// test/memory-transport.ts
import type { SocketStatus, SocketTransport } from 'kitr/realtime'
import { topicFor } from 'kitr/realtime'

type Handler = (event: string, data: unknown) => void

export function createMemoryTransport() {
  const topics = new Map<string, Set<Handler>>()
  const sent: Array<{ channel: string; params: unknown; event: string; data: unknown }> = []
  const transport: SocketTransport & {
    push(channel: string, params: unknown, event: string, data: unknown): void
    sent: typeof sent
  } = {
    status: 'open' as SocketStatus,
    onStatus: () => () => {},
    subscribe(channel, params, onEvent) {
      const topic = topicFor(channel, params)
      if (!topics.has(topic)) topics.set(topic, new Set())
      topics.get(topic)!.add(onEvent)
      return () => topics.get(topic)?.delete(onEvent)
    },
    send(channel, params, event, data) {
      sent.push({ channel, params, event, data })
    },
    close() {
      topics.clear()
    },
    push(channel, params, event, data) {
      for (const handler of topics.get(topicFor(channel, params)) ?? []) handler(event, data)
    },
    sent,
  }
  return transport
}
```

Use it where the app expects a transport. `channel()`, `useChannel` and `useRealtimeStatus` only call these five members:

```tsx
// app/features/projects/project-title.test.tsx
import { act, screen } from '@testing-library/react'
import { queryProvider } from 'kitr/query'
import { useChannel } from 'kitr/realtime/react'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { expect, it } from 'vitest'
import { projectChannel } from '#app/channels/projects'
import { createMemoryTransport } from '../../../test/memory-transport'

const transport = createMemoryTransport()

function LastProjectName({ id }: { id: string }) {
  const live = useChannel(transport, projectChannel, { id })
  return <p>{live.lastEvent?.event === 'updated' ? live.lastEvent.data.name : 'Waiting'}</p>
}

it('shows the renamed project', async () => {
  const app = await createTestApp({ providers: [queryProvider] })
  renderWithKitr(<LastProjectName id="prj_1" />, { app })
  act(() =>
    transport.push('projects', { id: 'prj_1' }, 'updated', {
      id: 'prj_1',
      name: 'Apollo launch',
      teamId: 'team_acme',
    }),
  )
  expect(await screen.findByText('Apollo launch')).toBeTruthy()
})
```

| Member | Description |
| --- | --- |
| `subscribe(channel, params, onEvent, onError?)` | Start receiving events for a topic. Returns the unsubscribe function. |
| `send(channel, params, event, data)` | Send a client event to the server. |
| `close()` | Close the connection. |
| `status` | `'connecting'`, `'open'` or `'closed'`. |
| `onStatus(listener)` | Listen for status changes. Returns the remove function. |

A real transport also resubscribes after reconnecting and calls `onError` with a kitr error shape. Read `createSseTransport` in the source for a short complete example, and see [`SocketTransport`](/packages/realtime/api) in the API reference.

## Next steps

- [API reference](/packages/realtime/api): every export of the seven entry points.
- [query](/packages/query): the cache that `effects` write to, and `useSubscription`.
- [server](/packages/server): `createServer`, `listen` and shutdown.
- [crossws](https://crossws.unjs.io) and [Socket.IO](https://socket.io/docs/v4/): the libraries underneath.
- [Getting started](/docs/getting-started): the `realtime` kit, a chat room built on these pieces.


# Router API

Source: https://kitr.dev/packages/router/api

Every export of `kitr/router`, read from the published type definitions. The [guide](/packages/router) shows them in use.

## kitr/router

Re-exports `@tanstack/history`, `@tanstack/react-router`, `@tanstack/router-core` unchanged, plus the following.

### can

```ts
function can(permission: string, options?: {
  subject?: unknown;
  to?: string;
}): ({ context }: {
  context: {
    session?: GuardSession | null;
  };
}) => void;
```

`beforeLoad` permission guard: passes when `context.session.can(permission, subject)` is true.
Otherwise throws a FORBIDDEN KitrError (403) that the route's error screen renders, or redirects when `to` is given.

### createKitrRouter

```ts
function createKitrRouter<TRouteTree extends AnyRoute>(options: CreateKitrRouterOptions<TRouteTree>): Router<TRouteTree, 'never', true>;
```

`createRouter` with kitr's defaults: queryClient and app in context, intent
preload, scroll restoration, default pending/error/not-found components,
and the app's providers wrapped around the whole tree.

With `@kitr/query` installed, loaders can `context.queryClient.ensureQueryData(...)`.

### DefaultError

```ts
function DefaultError({ error, reset }: ErrorComponentProps): import("react").JSX.Element;
```

The default error screen: the KitrError's message (or "Something went wrong"), a "Try again" button
that reloads the route and a "Go home" link. FORBIDDEN errors read "You don't have access to this page."

### DefaultNotFound

```ts
function DefaultNotFound(): import("react").JSX.Element;
```

The default not-found screen: "Page not found" and a "Go home" link, for unknown URLs and thrown `notFound()`.

### DefaultPending

```ts
function DefaultPending(): import("react").JSX.Element;
```

The default loading screen: a spinner with "Loading…" for screen readers (`data-kitr="pending"`).
`createKitrRouter` uses it for every route; override with `defaultPendingComponent` or a route's `pendingComponent`.

### guards

```ts
function guards<Ctx>(...fns: Array<(ctx: Ctx) => unknown | Promise<unknown>>): (ctx: Ctx) => Promise<Record<string, unknown>>;
```

Compose several `beforeLoad` guards into one. They run in order and are awaited; the objects
they return are merged into the route context, and the first throw stops the rest.

### requireAuth

```ts
function requireAuth(options?: RequireAuthOptions): ({ context, location }: {
  context: {
    session?: GuardSession | null;
  };
  location: {
    href: string;
  };
}) => {
  session: GuardSession;
};
```

`beforeLoad` guard. Reads `context.session` (set by `@kitr/auth` or your own
provider) and redirects anonymous users, remembering where they were going.

```ts
export const Route = createFileRoute('/_app')({ beforeLoad: requireAuth() })
```

### CreateKitrRouterOptions

```ts
interface CreateKitrRouterOptions<TRouteTree extends AnyRoute> extends Omit<RouterOptions<TRouteTree, 'never', false, any, any>, 'context'> {
  /** The app from `app/app.ts`. Put in every route's context as `context.app`; forked per request on the server. */
  app: KitrApp;
  /** Defaults to the container's `queryClient` (from @kitr/query). */
  queryClient?: QueryClient;
  /** Extra context merged into every route (e.g. `session`). */
  context?: Record<string, unknown>;
}
```

Options of `createKitrRouter`: TanStack's router options without `context`, plus the kitr app and extra context.

### GuardSession

```ts
interface GuardSession {
  /** The signed-in user. `requireAuth()` redirects when it is missing or null. */
  user?: unknown | null;
  /** Answers `can(permission, { subject })`. Without it, every `can()` check fails. */
  can?: (permission: string, subject?: unknown) => boolean;
}
```

What the guards read from `context.session`: a user when signed in, and an optional permission check.

### KitrRouterContext

```ts
interface KitrRouterContext {
  /** The query client loaders fill with `ensureQueryData`. Per request on the server. */
  queryClient: QueryClient;
  /** The kitr app, forked per request on the server. Read services with `context.app.container.use()`. */
  app: KitrApp;
}
```

The router context every kitr route sees. Packages extend it by augmentation:

```ts
declare module '@kitr/router' { interface KitrRouterContext { session: Session | null } }
```

### RequireAuthOptions

```ts
interface RequireAuthOptions {
  /** Where to send anonymous users. Default `/sign-in`. */
  to?: string;
  /** Name of the search param carrying the original URL. Default `redirect`. */
  redirectParam?: string | false;
}
```

Options of `requireAuth()`: where anonymous visitors go and which search param remembers their page.

### RouterContextWith

```ts
type RouterContextWith<T> = KitrRouterContext & T;
```

The router context plus your own fields, for typing a route's context without augmenting `KitrRouterContext`.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Router

Source: https://kitr.dev/packages/router

Every app has pages: a dashboard, a list of projects, one project, a sign-in screen. With `kitr/router` each page is a file in `app/routes`. Add `app/routes/projects/$id.tsx` and `/projects/42` exists, with `id` typed in the component, the loader and every `<Link>` that points at it.

`kitr/router` is [TanStack Router](https://tanstack.com/router/latest), re-exported unchanged, rendered by [TanStack Start](https://tanstack.com/start/latest). On top it adds `createKitrRouter` (the router with kitr's defaults and the app in context), default loading, error and not-found screens, and three `beforeLoad` guards: `requireAuth`, `can` and `guards`.

It runs in the browser, and on the server when the web platform renders pages there. A server-only project has no pages and no router; its HTTP routes come from [api](/packages/api).

This guide follows Acme's project tracker at `app.acme.com`: a projects list, one page per project, a signed-in area for Ada's team, and a settings page only admins can open.

## Install

The web, desktop and mobile [platforms](/docs/platforms) require the router, so `kitr new` and `kitr add web` install it, and every UI kit has it. To add it to a project by hand:

```sh
kitr add router
```

What `kitr add` does:

- Adds [react](/packages/react) first if the project does not have it, because the router requires it.
- Installs `@kitr/router`, `@tanstack/react-router` and `@tanstack/react-start`, and as dev dependencies `@tanstack/router-plugin` and `@tanstack/react-router-devtools`.
- Adds `'@kitr/router'` to `packages` in `kitrrc.ts`. The router registers no provider; `createKitrRouter` does its wiring.
- Writes `app/router.tsx`, which creates the router (shown under Configure).
- Writes `app/client.tsx`, Start's client entry, which boots the app before it hydrates the page.
- Writes three routes: `app/routes/__root.tsx` (the HTML document, with a two-link nav and `kitr/theme/styles.css`), `app/routes/index.tsx` (`/`) and `app/routes/about.tsx` (`/about`).
- Adds a `router` section to `AGENTS.md`: routes are files in `app/routes`, `app/routeTree.gen.ts` is generated, route files import `createFileRoute` from `@tanstack/react-router`, everything else from `kitr/router`, and the root route stays platform-neutral.
- Adds no config file, no environment variables and no scripts.

`kitr add` skips any of these files that already exists. It asks no questions; `--no-install` skips the package manager and `--dry-run` prints the plan.

```sh
kitr add router --dry-run
```

`kitr remove router` removes the packages, the `kitrrc.ts` entry and the `AGENTS.md` section. It leaves `app/router.tsx`, `app/client.tsx` and `app/routes/` in place, because they are your pages now.

## Configure

`kitr/router` has no config file. You configure it where it is created, in `app/router.tsx`, which `kitr add router` writes:

```tsx
// app/router.tsx
import { createKitrRouter } from 'kitr/router'
import { app } from './app'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  return createKitrRouter({ routeTree, app })
}

declare module '@tanstack/react-router' {
  interface Register {
    router: ReturnType<typeof getRouter>
  }
}
```

TanStack Start calls `getRouter()` once in the browser and once per request on the server. The `Register` block is what makes every `<Link to>`, `useParams` and `useSearch` in the app type-checked against your routes.

`createKitrRouter` accepts every [`createRouter` option](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType) except `context`, and sets different defaults for some of them:

| Option | Default | Description |
| --- | --- | --- |
| `routeTree` | required | The generated tree from `app/routeTree.gen.ts`. |
| `app` | required | The kitr app from `app/app.ts`. Put in every route's context as `context.app`, forked per request on the server. |
| `queryClient` | the container's `queryClient` | The [query](/packages/query) client put in context as `context.queryClient`. Read from the container the first time a loader asks, so it works before boot. |
| `context` | `{}` | Extra fields merged into every route's context, such as `session`. |
| `defaultPreload` | `'intent'` | Links load their page's code and data on hover or focus. |
| `defaultPreloadStaleTime` | `0` | Preloads always run the loader, so the query cache decides what is fresh. |
| `scrollRestoration` | `true` | Back and forward restore the scroll position. |
| `defaultPendingComponent` | `DefaultPending` | What a route shows while its loader runs. |
| `defaultErrorComponent` | `DefaultError` | What a route shows when its loader or component throws. |
| `defaultNotFoundComponent` | `DefaultNotFound` | What shows for an unknown URL or a thrown `notFound()`. |
| `defaultStructuralSharing` | `true` | Search params and loader data keep their identity when unchanged, so memoised components do not re-render. |
| `history` | browser history | Pass `createMemoryHistory()` in tests. |

`createKitrRouter` also sets `Wrap` to render `KitrProvider`, so the app's providers wrap every page. A `Wrap` you pass is replaced; wrap the tree from a provider's `wrap()` instead.

## Add your first page

Create a file under `app/routes`, or let `kitr make:route projects` write it:

```tsx
// app/routes/projects/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { Link } from 'kitr/router'

const projects = [
  { id: 'apollo', name: 'Apollo', team: 'Platform' },
  { id: 'hermes', name: 'Hermes', team: 'Billing' },
]

export const Route = createFileRoute('/projects/')({
  component: ProjectsPage,
})

function ProjectsPage() {
  return (
    <main>
      <h1>Projects</h1>
      <ul>
        {projects.map((project) => (
          <li key={project.id}>
            <Link to="/projects/$id" params={{ id: project.id }}>
              {project.name}
            </Link>{' '}
            ({project.team})
          </li>
        ))}
      </ul>
    </main>
  )
}
```

Run `kitr dev` and open `/projects`. You see the two projects as links. While `kitr dev` runs, the route generator adds the file to `app/routeTree.gen.ts`; never edit that file by hand.

Route files import `createFileRoute` from `@tanstack/react-router` because the generator owns that line and rewrites it. Everything else, such as `Link`, `useNavigate` and `Outlet`, comes from `kitr/router`. `kitr doctor` warns about any other direct `@tanstack/react-router` import.

## Map files to URLs

| File | URL |
| --- | --- |
| `app/routes/index.tsx` | `/` |
| `app/routes/about.tsx` | `/about` |
| `app/routes/projects/index.tsx` | `/projects/` |
| `app/routes/projects/$id.tsx` | `/projects/:id`, with `params.id` |
| `app/routes/projects/$id/settings.tsx` | `/projects/:id/settings` |
| `app/routes/_app.tsx` | A layout with no URL segment; wraps every route in `app/routes/_app/` |
| `app/routes/_app/dashboard.tsx` | `/dashboard`, inside the `_app` layout |
| `app/routes/files/$.tsx` | `/files/*`, the rest of the path in `params._splat` |
| `app/routes/__root.tsx` | The HTML document around every page |

The full naming rules, including route groups and lazy routes, are in TanStack's [file-based routing guide](https://tanstack.com/router/latest/docs/framework/react/routing/file-based-routing).

## Read path params

A `$name` segment becomes a typed param. Read it with `Route.useParams()`:

```tsx
// app/routes/projects/$id.tsx
import { createFileRoute } from '@tanstack/react-router'
import { Link } from 'kitr/router'

export const Route = createFileRoute('/projects/$id')({
  component: ProjectPage,
})

function ProjectPage() {
  const { id } = Route.useParams() // '/projects/apollo' → { id: 'apollo' }
  return (
    <main>
      <h1>Project {id}</h1>
      <Link to="/projects">All projects</Link>
    </main>
  )
}
```

`<Link to="/projects/$id">` without `params` is a type error, and so is a `to` that matches no route file. That is the `Register` block in `app/router.tsx` at work.

## Read and write search params

Declare what the query string may hold with `validateSearch`. The result is typed in the component and in every link to the route:

```tsx
// app/routes/projects/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { Link } from 'kitr/router'

type ProjectsSearch = { team?: string; page: number }

export const Route = createFileRoute('/projects/')({
  validateSearch: (search: Record<string, unknown>): ProjectsSearch => ({
    team: typeof search.team === 'string' ? search.team : undefined,
    page: Number(search.page ?? 1) || 1,
  }),
  component: ProjectsPage,
})

function ProjectsPage() {
  const { team, page } = Route.useSearch() // '/projects?team=Billing' → { team: 'Billing', page: 1 }
  return (
    <main>
      <h1>{team ? `${team} projects` : 'All projects'}</h1>
      <Link to="/projects" search={{ team, page: page + 1 }}>
        Next page
      </Link>
    </main>
  )
}
```

A schema library works too: pass a [Zod](https://zod.dev) schema's `parse` as `validateSearch`. For tables bound to the URL, [table](/packages/table) reads and writes these params for you.

## Navigate from code

After a form submits or an action finishes, navigate with `useNavigate`:

```tsx
// app/features/projects/archive-button.tsx
import { useNavigate } from 'kitr/router'

export function ArchiveButton({ id }: { id: string }) {
  const navigate = useNavigate()
  async function archive() {
    await fetch(`/api/projects/${id}/archive`, { method: 'POST' })
    await navigate({ to: '/projects', search: { page: 1 } })
  }
  return (
    <button type="button" onClick={archive}>
      Archive
    </button>
  )
}
```

`navigate` takes the same typed `to`, `params` and `search` as `<Link>`. Use `<Link>` for anything the user clicks to move; it preloads on hover, renders a real `<a>` and works with a middle click. Keep `navigate` for moves that follow an action.

## Load data before the page renders

A loader runs before the route renders, on the server during server rendering and in the browser on every navigation. With [query](/packages/query), the loader fills the cache and the component reads the same entry, so the page never shows a spinner on first load:

```ts
// app/features/projects/queries.ts
import { createKeys } from 'kitr/app'
import { defineQuery } from 'kitr/query'

export interface Project {
  id: string
  name: string
  team: string
}

export const projectKeys = createKeys('projects')

export const projectQuery = defineQuery({
  key: (id: string) => projectKeys.detail(id),
  fetch: async (id, { signal }): Promise<Project> => {
    const res = await fetch(`https://api.acme.com/projects/${id}`, { signal })
    return (await res.json()) as Project
  },
})
```

```tsx
// app/routes/projects/$id.tsx
import { createFileRoute } from '@tanstack/react-router'
import { Link } from 'kitr/router'
import { useSuspenseQuery } from 'kitr/query'
import { projectQuery } from '#app/features/projects/queries'

export const Route = createFileRoute('/projects/$id')({
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData(projectQuery.options(params.id)),
  component: ProjectPage,
})

function ProjectPage() {
  const { id } = Route.useParams()
  const { data: project } = useSuspenseQuery(projectQuery.options(id))
  return (
    <main>
      <h1>{project.name}</h1>
      <p>Team: {project.team}</p>
      <Link to="/projects">All projects</Link>
    </main>
  )
}
```

`context.queryClient` comes from `createKitrRouter`. It is the container's `queryClient`, and on the server it belongs to this request alone. Because links preload on intent, hovering the "Apollo" link already runs this loader.

Without query, return data from the loader and read it with `Route.useLoaderData()`. Prefer the query version: the cache is shared with every other component that shows the project, and mutations can refresh it.

## Use services in loaders

Loaders and guards are not components, so they cannot call `useService`. Read services from `context.app`:

```tsx
// app/routes/teams/$team.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/teams/$team')({
  loader: async ({ context, params }) => {
    const http = context.app.container.use('http')
    return http.get(`teams/${params.team}`).json<{ name: string; members: string[] }>()
  },
  component: TeamPage,
})

function TeamPage() {
  const team = Route.useLoaderData()
  return (
    <p>
      {team.name}: {team.members.join(', ')}
    </p>
  )
}
// /teams/platform → "Platform: Ada, Grace, Linus"
```

The router boots the app before the first loader runs, so every service is ready. Don't import `app` from `#app/app` in a loader: on the server, `context.app` is a per-request fork of it, and the shared app would leak one visitor's request-scoped services into another's page.

## Add a layout

A file whose name starts with `_` is a layout without a URL segment. It renders `<Outlet />` where the child page goes:

```tsx
// app/routes/_app.tsx
import { createFileRoute } from '@tanstack/react-router'
import { Link, Outlet } from 'kitr/router'

export const Route = createFileRoute('/_app')({
  component: AppLayout,
})

function AppLayout() {
  return (
    <div className="app-layout">
      <nav>
        <Link to="/dashboard">Dashboard</Link>
        <Link to="/projects">Projects</Link>
      </nav>
      <Outlet />
    </div>
  )
}
```

Every route in `app/routes/_app/` now renders inside this layout. Navigating between them keeps the layout mounted and replaces only the outlet.

## Show loading, error and not-found states

`createKitrRouter` gives every route three screens without you writing them:

| Component | Shows | Markup |
| --- | --- | --- |
| `DefaultPending` | A spinner with "Loading…" for screen readers, while a loader runs. | `role="status"`, `data-kitr="pending"` |
| `DefaultError` | The error's title and message, a "Try again" button and a "Go home" link. | `role="alert"`, `data-kitr="error"`, `data-code` set to the error code |
| `DefaultNotFound` | "Page not found" and a "Go home" link. | `data-kitr="not-found"` |

They are styled by `kitr/theme/styles.css`, which the root route imports, through the `.kitr-pending`, `.kitr-error` and `.kitr-not-found` classes. TanStack shows the pending screen only when a loader takes longer than `defaultPendingMs` (one second by default), so fast pages never flash it.

Override one route by giving it its own component:

```tsx
// app/routes/projects/$id.tsx
import { createFileRoute } from '@tanstack/react-router'
import { type ErrorComponentProps, Link } from 'kitr/router'
import { toKitrError } from 'kitr/app'

export const Route = createFileRoute('/projects/$id')({
  pendingComponent: () => <p>Loading project…</p>,
  errorComponent: ProjectError,
  component: () => <p>Project</p>,
})

function ProjectError({ error }: ErrorComponentProps) {
  const err = toKitrError(error)
  return (
    <div role="alert">
      <p>Could not open this project ({err.code}).</p>
      <Link to="/projects">Back to projects</Link>
    </div>
  )
}
```

Override them for the whole app in `app/router.tsx`:

```tsx
// app/router.tsx
import { createKitrRouter } from 'kitr/router'
import { app } from './app'
import { AcmeError, AcmeNotFound, AcmeSpinner } from './components/route-states'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  return createKitrRouter({
    routeTree,
    app,
    defaultPendingComponent: AcmeSpinner,
    defaultErrorComponent: AcmeError,
    defaultNotFoundComponent: AcmeNotFound,
  })
}
```

The defaults are exported, so a custom screen can render one inside its own layout: `import { DefaultError } from 'kitr/router'`.

## Throw errors from loaders

Throw a `KitrError` from a loader and `DefaultError` shows its message as the title, with its code in `data-code`:

```tsx
// app/routes/projects/$id/archive.tsx
import { createFileRoute } from '@tanstack/react-router'
import { KitrError } from 'kitr/app'

export const Route = createFileRoute('/projects/$id/archive')({
  loader: ({ params }) => {
    if (params.id === 'apollo') throw new KitrError('CONFLICT', 'Already archived')
    return { id: params.id }
  },
  component: () => <p>Archive this project?</p>,
})
// /projects/apollo/archive renders:
// <div role="alert" data-kitr="error" data-code="CONFLICT"><h2>Already archived</h2>…
```

| What was thrown | Title | Body |
| --- | --- | --- |
| A `KitrError` | The error's message | The error's message |
| A `KitrError` with code `FORBIDDEN` | The error's message | "You don't have access to this page." |
| Anything else | "Something went wrong" | The error's message |

"Try again" invalidates the router and resets the error boundary, so the loader runs again. Errors from [http](/packages/http), [actions](/packages/actions) and [query](/packages/query) are already `KitrError`s.

For a missing record, throw TanStack's `notFound()` instead. The route's not-found screen renders, not the error screen:

```tsx
// app/routes/projects/$id.tsx
import { createFileRoute } from '@tanstack/react-router'
import { notFound } from 'kitr/router'

const projects: Record<string, { name: string }> = { apollo: { name: 'Apollo' } }

export const Route = createFileRoute('/projects/$id')({
  loader: ({ params }) => {
    const project = projects[params.id]
    if (!project) throw notFound()
    return project
  },
  component: () => <h1>{Route.useLoaderData().name}</h1>,
})
// /projects/zeus → "Page not found"
```

## Protect pages behind sign-in

`requireAuth()` is a `beforeLoad` guard. Put it on a layout and every route under it needs a signed-in user:

```tsx
// app/routes/_app.tsx
import { createFileRoute } from '@tanstack/react-router'
import { Outlet, requireAuth } from 'kitr/router'

export const Route = createFileRoute('/_app')({
  beforeLoad: requireAuth(),
  component: () => <Outlet />,
})
```

The guard reads `context.session`. When `session?.user` is missing, it throws a redirect to `/sign-in` with the page the visitor wanted in the `redirect` search param: Linus, signed out, opening `/projects/apollo?tab=tasks` lands on `/sign-in` with `redirect` set to `/projects/apollo?tab=tasks`. When there is a user, it returns `{ session }`, which TanStack merges into the context of every child route.

| Option | Default | Description |
| --- | --- | --- |
| `to` | `'/sign-in'` | Where anonymous visitors go. |
| `redirectParam` | `'redirect'` | The search param that carries the original URL. `false` sends no param. |

```tsx
// app/routes/_app.tsx
import { createFileRoute } from '@tanstack/react-router'
import { Outlet, requireAuth } from 'kitr/router'

export const Route = createFileRoute('/_app')({
  beforeLoad: requireAuth({ to: '/login', redirectParam: 'next' }),
  component: () => <Outlet />,
})
// signed out at /dashboard → /login, with search { next: '/dashboard' }
```

After sign-in, send the visitor back:

```tsx
// app/routes/sign-in.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useNavigate } from 'kitr/router'

export const Route = createFileRoute('/sign-in')({
  validateSearch: (search: Record<string, unknown>) => ({
    redirect: typeof search.redirect === 'string' ? search.redirect : '/dashboard',
  }),
  component: SignInPage,
})

function SignInPage() {
  const { redirect } = Route.useSearch()
  const navigate = useNavigate()
  async function signIn() {
    // ... sign in with kitr/auth
    await navigate({ to: redirect })
  }
  return (
    <button type="button" onClick={signIn}>
      Sign in as ada@acme.com
    </button>
  )
}
```

The guard only sees a session if you put one in the router context, through `createKitrRouter`'s `context` option. The session can come from [auth](/packages/auth) or from your own provider; see "Add fields to the router context" below.

> **Warning**
> Route guards decide what the browser shows. They do not protect data: anyone can call your API without loading the page. Check the session again on the server, in the API route or action that returns the data.

## Check a permission

`can(permission)` asks `context.session.can(permission, subject)`. Without permission it throws a `FORBIDDEN` `KitrError` (status 403), which the route's error screen shows as "You don't have access to this page.":

```tsx
// app/routes/_app/settings.tsx
import { createFileRoute } from '@tanstack/react-router'
import { can } from 'kitr/router'

export const Route = createFileRoute('/_app/settings')({
  beforeLoad: can('teams.manage'),
  component: () => <h1>Team settings</h1>,
})
// Grace (member) opening /settings: the error screen, title 'Missing permission "teams.manage"'
```

Pass `to` to redirect instead of showing the error:

```tsx
// app/routes/_app/billing.tsx
import { createFileRoute } from '@tanstack/react-router'
import { can } from 'kitr/router'

export const Route = createFileRoute('/_app/billing')({
  beforeLoad: can('invoices.view', { to: '/upgrade' }),
  component: () => <h1>Invoices</h1>,
})
```

`subject` is fixed when the route file loads. For a check that depends on the URL, call the guard inside `beforeLoad` with the subject you build from the params:

```tsx
// app/routes/_app/projects/$id/edit.tsx
import { createFileRoute } from '@tanstack/react-router'
import { can } from 'kitr/router'

export const Route = createFileRoute('/_app/projects/$id/edit')({
  beforeLoad: (ctx) => can('projects.update', { subject: { id: ctx.params.id } })(ctx),
  component: () => <h1>Edit project</h1>,
})
```

A session without a `can` function, or no session at all, fails every check. The guards type-check against `context.session`, so declare `session` on `KitrRouterContext` (see "Add fields to the router context"). Inside components, [auth](/packages/auth)'s `useCan()` hides buttons the user cannot use; the guard stops the page.

## Combine guards

`guards(a, b, ...)` runs several `beforeLoad` functions in order, awaits each one and merges the objects they return. The first one that throws stops the rest:

```tsx
// app/routes/_app/admin.tsx
import { createFileRoute } from '@tanstack/react-router'
import { can, guards, requireAuth } from 'kitr/router'

export const Route = createFileRoute('/_app/admin')({
  beforeLoad: guards(requireAuth(), can('admin.access')),
  component: () => <h1>Admin</h1>,
})
```

Your own guards fit in the same list. Return an object to add it to the route context. When a guard needs the route's params, build the list inside `beforeLoad`:

```tsx
// app/routes/_app/teams/$team.tsx
import { createFileRoute } from '@tanstack/react-router'
import { guards, requireAuth } from 'kitr/router'

const loadTeam = async (slug: string) => ({
  team: { slug, name: slug === 'platform' ? 'Platform' : 'Billing' },
})

export const Route = createFileRoute('/_app/teams/$team')({
  beforeLoad: (ctx) => guards(requireAuth(), () => loadTeam(ctx.params.team))(ctx),
  component: TeamPage,
})

function TeamPage() {
  const { team } = Route.useRouteContext()
  return <h1>{team.name}</h1>
}
// /teams/platform → beforeLoad returns { session, team }, and the page shows "Platform"
```

When two guards return the same key, the later one wins.

## Add fields to the router context

Pass extra context with `context` and declare its type once, so every `beforeLoad` and loader sees it. This is how a session reaches the guards. Here it comes from an app service of your own named `session`:

```tsx
// app/router.tsx
import { createKitrRouter } from 'kitr/router'
import { app } from './app'
import { routeTree } from './routeTree.gen'

interface AcmeSession {
  user: { id: string; email: string; role: 'admin' | 'member' } | null
  can: (permission: string, subject?: unknown) => boolean
}

export function getRouter() {
  return createKitrRouter({
    routeTree,
    app,
    context: {
      // A getter, so guards read the session the app restored during boot, not the one at creation.
      get session(): AcmeSession | null {
        return app.container.has('session') ? (app.container.use('session') as AcmeSession) : null
      },
    },
  })
}

declare module '@tanstack/react-router' {
  interface Register {
    router: ReturnType<typeof getRouter>
  }
}

declare module '@kitr/router' {
  interface KitrRouterContext {
    session: AcmeSession | null
  }
}
```

With [auth](/packages/auth), read the session from its `auth` service the same way:

```tsx
// app/router.tsx
import type { Session } from 'kitr/auth'
import { createKitrRouter } from 'kitr/router'
import type { User } from '#app/abilities'
import { app } from './app'
import { routeTree } from './routeTree.gen'

export function getRouter() {
  return createKitrRouter({
    routeTree,
    app,
    context: {
      // A live getter, so `requireAuth()` sees the session the auth provider restores during boot.
      get session() {
        return app.container.has('auth') ? (app.container.use('auth').session as Session<User>) : null
      },
    },
  })
}

declare module '@kitr/router' {
  interface KitrRouterContext {
    session: Session<User> | null
  }
}
```

`KitrRouterContext` starts with `app` and `queryClient`. The root route is created with `createRootRouteWithContext<KitrRouterContext>()`, so what you declare here is typed in every route. Augment `'@kitr/router'`, the module that declares the interface.

Use a getter when the value changes after the router is created. TanStack Start builds the router before the app boots, so a plain `session: app.container.use('session')` would read it too early and throw `No binding named "session"`.

## Set the page title and meta tags

Each route can add tags to the document head with `head`. The root route renders them through `<HeadContent />`:

```tsx
// app/routes/projects/$id.tsx
import { createFileRoute } from '@tanstack/react-router'
import { projectQuery } from '#app/features/projects/queries'

export const Route = createFileRoute('/projects/$id')({
  loader: ({ context, params }) =>
    context.queryClient.ensureQueryData(projectQuery.options(params.id)),
  head: ({ loaderData }) => ({
    meta: [{ title: `${loaderData?.name ?? 'Project'} · Acme` }],
  }),
  component: () => null,
})
```

For canonical URLs, Open Graph tags and sitemaps, use [seo](/packages/seo).

## Render on the server

The root route renders the whole HTML document:

```tsx
// app/routes/__root.tsx
import type { KitrRouterContext } from 'kitr/router'
import { HeadContent, Link, Outlet, Scripts, createRootRouteWithContext } from 'kitr/router'
import type { ReactNode } from 'react'
import css0 from 'kitr/theme/styles.css?url'

export const Route = createRootRouteWithContext<KitrRouterContext>()({
  head: () => ({
    meta: [{ charSet: 'utf-8' }, { name: 'viewport', content: 'width=device-width, initial-scale=1' }],
    links: [{ rel: 'stylesheet', href: css0 }],
  }),
  component: RootLayout,
})

function RootLayout() {
  return (
    <RootDocument>
      <nav style={{ display: 'flex', gap: 12, padding: 12 }}>
        <Link to="/">Home</Link>
        <Link to="/about">About</Link>
      </nav>
      <Outlet />
    </RootDocument>
  )
}

/** The HTML shell. Start streams it on the server and hydrates it on the client. */
function RootDocument({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}
```

On the web platform, [`mode`](/docs/platforms) decides what happens with it: `ssr` streams it from the server on every request, `static` prerenders it at build time, and `spa` ships one shell that renders in the browser. Desktop and mobile apps always use the shell. Write the root route once and it works in all of them; don't branch on the platform inside it.

On the server, each request gets its own router and its own fork of the app (`app.fork()`), so request-scoped services such as the query cache never leak between visitors. The router also boots the app before its first `load()`, so a loader never sees a provider that has not registered yet.

## Reach the router from a service

`createKitrRouter` binds the router in the container as `router`, so code that is not a component can navigate without importing the route tree:

```ts
// app/features/projects/open-project.ts
import { app } from '#app/app'

export function openProject(id: string) {
  const router = app.container.use('router')
  return router.navigate({ to: '/projects/$id', params: { id } })
}
```

The binding is typed as TanStack's `AnyRouter`, so `to` is not checked here. Inside components, prefer `useNavigate()`, which is.

## Devtools

With [devtools](/packages/devtools) installed, every resolved navigation is logged to the overlay's log under the `router` source: `navigated /projects/apollo` when the path changed, `resolved /projects/apollo` when only the search did. Each entry carries the previous path and the new search params.

## Errors

| Code | When | What to do |
| --- | --- | --- |
| `FORBIDDEN` (403) | `can(permission)` failed and no `to` was given. Message: `Missing permission "<permission>"`. | Give the user the permission, hide the link with `useCan()`, or pass `to` to redirect. |
| redirect | `requireAuth()` found no `session.user`. Not an error: TanStack follows it. | Put a session in context with `createKitrRouter({ context })`. |
| not found | No route matches, or a loader threw `notFound()`. | Add the route file, or check the id. |
| `[kitr] No binding named "session"` | The router context read a service before the app booted. | Read it through a getter, as in "Add fields to the router context". |
| `Something went wrong` | A loader threw something that is not a `KitrError`. | Throw a `KitrError` with a code and message the user can act on. |

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:route <path>` | Writes a route file under `app/routes` with a component and a commented loader. |

```sh
kitr make:route projects/$id
```

This writes `app/routes/projects/$id.tsx`:

```tsx
// app/routes/projects/$id.tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/projects/$id')({
  // loader: ({ context }) => context.queryClient.ensureQueryData(idQuery.options()),
  component: IdPage,
})

function IdPage() {
  return (
    <div>
      <h1>Id</h1>
    </div>
  )
}
```

`projects/index` writes `app/routes/projects/index.tsx` for the path `/projects/`; `/` writes `app/routes/index.tsx`. `--force` overwrites an existing file. `kitr eject stub route` copies the template to `stubs/route.ts` so you can change what every new route looks like. Quote the argument in shells that expand `$`: `kitr make:route 'projects/$id'`.

`kitr doctor` checks the router too: it reports when `app/routeTree.gen.ts` has not been generated yet (run `kitr dev` once) and warns about imports from `@tanstack/react-router` outside the generator's `createFileRoute` line.

## Testing

Build the router in a test with `createKitrRouter`, a test app and a memory history, then render it with `RouterProvider`:

```tsx
// app/routes/projects.test.tsx
import { createTestApp } from 'kitr/testing'
import {
  createKitrRouter,
  createMemoryHistory,
  createRootRouteWithContext,
  createRoute,
  type KitrRouterContext,
  Outlet,
  RouterProvider,
} from 'kitr/router'
import { act, render, screen } from '@testing-library/react'
import { describe, expect, it } from 'vitest'

function routes() {
  const root = createRootRouteWithContext<KitrRouterContext>()({ component: () => <Outlet /> })
  const project = createRoute({
    getParentRoute: () => root,
    path: '/projects/$id',
    loader: ({ params }) => ({ id: params.id, name: params.id === 'apollo' ? 'Apollo' : 'Hermes' }),
    component: function ProjectPage() {
      return <h1>{project.useLoaderData().name}</h1>
    },
  })
  return root.addChildren([project])
}

async function visit(path: string) {
  const app = await createTestApp()
  const router = createKitrRouter({
    routeTree: routes(),
    app,
    history: createMemoryHistory({ initialEntries: [path] }),
  })
  await act(async () => {
    render(<RouterProvider router={router} />)
    await router.load()
  })
  return router
}

describe('project page', () => {
  it('renders the project from the loader', async () => {
    await visit('/projects/apollo')
    expect(await screen.findByRole('heading', { name: 'Apollo' })).toBeTruthy()
  })

  it('shows the not-found page for an unknown URL', async () => {
    await visit('/teams')
    expect(await screen.findByText('Page not found')).toBeTruthy()
  })
})
```

Testing with the generated `routeTree` from `app/routeTree.gen.ts` works the same way; build the small tree above when you want a test that does not depend on every page.

Guards are plain functions, so test them without rendering. A redirect is thrown, and `isRedirect` recognises it:

```ts
// app/routes/guards.test.ts
import { can, isRedirect, requireAuth } from 'kitr/router'
import { describe, expect, it } from 'vitest'

const location = { href: '/projects/apollo?tab=tasks' }

describe('guards', () => {
  it('sends Linus to sign-in when signed out', () => {
    try {
      requireAuth()({ context: { session: null }, location })
      expect.unreachable()
    } catch (redirect: any) {
      expect(isRedirect(redirect)).toBe(true)
      expect(redirect.options.to).toBe('/sign-in')
      expect(redirect.options.search).toEqual({ redirect: '/projects/apollo?tab=tasks' })
    }
  })

  it('lets Ada in and keeps her session in context', () => {
    const session = { user: { id: 'ada' } }
    expect(requireAuth()({ context: { session }, location })).toEqual({ session })
  })

  it('refuses Grace without teams.manage', () => {
    const session = { user: { id: 'grace' }, can: (permission: string) => permission !== 'teams.manage' }
    expect(() => can('teams.manage')({ context: { session } })).toThrow(
      expect.objectContaining({ code: 'FORBIDDEN', status: 403 }),
    )
  })
})
```

To render one component that uses `Link` or `Route.useParams` without a full route tree, render it from a route's `component` in a small tree like the one above. Links need a router around them.

## Next steps

- [API reference](/packages/router/api): `createKitrRouter`, the guards and the default screens with their signatures.
- [TanStack Router documentation](https://tanstack.com/router/latest/docs/framework/react/overview): routing, search params, loaders and everything re-exported here.
- [Query](/packages/query): the cache that loaders fill and components read.
- [Auth](/packages/auth): the session the guards read, and `useCan()` for components.
- [Platforms](/docs/platforms): `ssr`, `static` and `spa` modes, and the desktop and mobile shells.


# Secure storage API

Source: https://kitr.dev/packages/secure-storage/api

Every export of `kitr/secure-storage`, `kitr/secure-storage/react`, `kitr/secure-storage/provider`, read from the published type definitions. The [guide](/packages/secure-storage) shows them in use.

## kitr/secure-storage

### createMemorySecureStorageDriver

```ts
function createMemorySecureStorageDriver(name?: string): SecureStorageDriver;
```

A vault in a `Map`, for tests and the server. `secure` is false; nothing survives a restart.

### createSecureStorage

```ts
function createSecureStorage(config?: SecureStorageConfig, app?: KitrApp): SecureStorage;
```

Build the `secureStorage` service. The driver is `config.driver`, else the vault registered on
`app`, else the encrypted web fallback in a browser or the memory driver on the server.

### createWebSecureStorageDriver

```ts
function createWebSecureStorageDriver(storage?: StorageDriver): SecureStorageDriver;
```

Encrypts values with AES-GCM before handing them to a `StorageDriver`. The key never leaves
the browser's key store, so the ciphertext in local storage cannot be read elsewhere.

### defineSecureItem

```ts
function defineSecureItem<T>(key: string, options?: SecureItemOptions<T>): (storage: SecureStorage) => SecureItem<T>;
```

A typed, subscribable secret: `const session = defineSecureItem<Session>('session')`.
Call it with a service to bind it, `session(app.container.use('secureStorage'))`, or pass it to `useSecureItem`.

### useSecureStorage

```ts
function useSecureStorage(app: KitrApp): SecureStorage;
```

The app's `secureStorage` service, outside React. Same as `app.container.use('secureStorage')`.

### defineConfig

```ts
const defineConfig: <const C extends SecureStorageConfig>(config: C) => C;
```

Types `config/secure-storage.ts`. Returns the object unchanged.

### SecureItem

```ts
interface SecureItem<T> {
  /** The key, without the service prefix. */
  key: string;
  /** Resolve the value, or undefined when missing. Corrupt or invalid values are removed. */
  get(): Promise<T | undefined>;
  /** Store the value and notify this item's subscribers. */
  set(value: T): Promise<void>;
  /** Delete the value and notify this item's subscribers with undefined. */
  remove(): Promise<void>;
  /** Hear writes made through this bound item; returns an unsubscribe function. */
  subscribe(listener: (value: T | undefined) => void): () => void;
}
```

A typed secret bound to a `SecureStorage` service, as returned by calling a `defineSecureItem` result.

### SecureItemOptions

```ts
interface SecureItemOptions<T> {
  /** Validate what comes back from the vault; invalid values are removed. */
  schema?: StandardSchemaV1<unknown, T>;
  /** Serialise with something other than JSON. */
  codec?: {
    encode(value: T): string;
    decode(raw: string): T;
  };
}
```

Options for `defineSecureItem`: a schema to check reads and a codec for non-JSON values.

### SecureStorage

```ts
interface SecureStorage {
  /** The active driver. */
  readonly driver: SecureStorageDriver;
  /** True when values live in an OS vault rather than the encrypted web fallback. */
  readonly secure: boolean;
  /** Resolve the string stored under `key`, or null. */
  get(key: string): Promise<string | null>;
  /** Store a string. Throws under `requireSecure` when no vault is registered. */
  set(key: string, value: string): Promise<void>;
  /** Delete a key. */
  remove(key: string): Promise<void>;
  /** Keys written through this service (not every item in the vault). */
  keys(): Promise<string[]>;
  /** Remove every key `keys()` returns, leaving other prefixes alone. */
  clear(): Promise<void>;
}
```

The `secureStorage` service: async string storage over the vault, under one key prefix.

### SecureStorageConfig

```ts
interface SecureStorageConfig {
  /** Prefix for every key. Default `kitr:secure:`. */
  prefix?: string;
  /** Replace the resolved driver (tests, custom vaults). */
  driver?: SecureStorageDriver;
  /** Where the web fallback keeps the ciphertext. Default: the app's local storage driver. */
  storage?: StorageDriver;
  /** Refuse to store anything when only the web fallback is available (production kiosks, banking). */
  requireSecure?: boolean;
}
```

Options for `config/secure-storage.ts` and `createSecureStorage()`.

### SecureStorageDriver

```ts
/** What a vault implements. Keys arrive with the service's prefix already added. */
interface SecureStorageDriver {
  /** Shown in devtools, such as `web-crypto` or `memory`. */
  name: string;
  /** Backed by hardware or an OS vault (false for the web fallback). */
  secure: boolean;
  /** Resolve the stored string, or null. */
  get(key: string): Promise<string | null>;
  /** Store a string. */
  set(key: string, value: string): Promise<void>;
  /** Delete a key. */
  remove(key: string): Promise<void>;
  /** Every stored key. Optional: without it the service lists keys written this session. */
  keys?(): Promise<string[]>;
}
```

What a vault implements. Keys arrive with the service's prefix already added.

## kitr/secure-storage/react

### useSecureItem

```ts
function useSecureItem<T>(define: (storage: SecureStorage) => SecureItem<T>): [
  T | undefined,
  (value: T | undefined) => Promise<void>,
  {
    loading: boolean;
    secure: boolean;
  }
];
```

Read and write one secret: `const [session, setSession, { loading }] = useSecureItem(sessionItem)`.
The value is `undefined` until the vault answers (and always on the server).

### useSecureStorage

```ts
function useSecureStorage(): SecureStorage;
```

The app's `secureStorage` service in a component.

## kitr/secure-storage/provider

### secureStorageProvider

```ts
const secureStorageProvider: import("@kitr/core").KitrProvider;
```

Binds `secureStorage` to the platform vault (registered by the mobile/desktop providers under
the `secure-storage` capability) or the encrypted web fallback. On the server it is an in-memory
store, so code that runs in both places needs no branches.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Secure storage

Source: https://kitr.dev/packages/secure-storage

A session token, a refresh token, an API key someone pasted into settings: these shouldn't sit in `localStorage` as plain text, where anything that reads the disk or the page can copy them. Phones and computers have a proper vault for secrets, and each has a different API. `kitr/secure-storage` gives you one async key-value service, `secureStorage`, and typed items on top of it, so the code that keeps Ada's session reads the same wherever the app runs.

A platform registers its vault as a driver: the iOS Keychain, the Android Keystore or Electron's [`safeStorage`](https://www.electronjs.org/docs/latest/api/safe-storage). In the browser, and anywhere no vault is registered, a fallback encrypts each value with AES-GCM through the [Web Crypto API](https://developer.mozilla.org/docs/Web/API/SubtleCrypto), under a key the browser keeps in IndexedDB and never lets out. kitr adds typed items with schema checks, a React hook, a `secure` flag that says which one you got, a switch that refuses the fallback, and a memory driver for tests.

It runs in the browser, in desktop and mobile shells, and on the server as an in-memory store. For values that are not secret, such as a theme or a draft order, use [Storage](/packages/storage): it is synchronous and renders on the server.

This guide follows Acme's app at `app.acme.com`: Ada signs in, her session token goes into secure storage, and signing out clears it.

## When to use it

Use secure storage for anything that grants access: session and refresh tokens, API keys, a PIN-protected value. Reads are async, so components get `undefined` until the vault answers.

Use [Storage](/packages/storage) for everything else. Its items are synchronous, can be read during the first render and on the server through cookies, and are cheaper to read. Don't put tokens there: Storage writes plain text.

## Install

```sh
kitr add secure-storage
```

What `kitr add` does:

- Adds [Storage](/packages/storage) first when the project does not have it yet, because `secure-storage` requires `storage`. Every kit except `blank` and `server` already includes it.
- Installs `@kitr/secure-storage`.
- Adds `() => import('@kitr/secure-storage/provider')` to `providers` in `kitrrc.ts`.
- Adds `@kitr/secure-storage` to `packages` in `kitrrc.ts`.
- Writes `config/secure-storage.ts` (shown under [Configure](#configure)).
- Writes `app/secure.ts` with one typed item, `sessionItem` (shown under [Store your first secret](#store-your-first-secret)).
- Adds a `## kitr: secure-storage` section to `AGENTS.md`: tokens and secrets go through `kitr/secure-storage` and `app/secure.ts`, never `defineStorage` or `localStorage`; `useSecureItem(item)` returns `[value, set, { loading, secure }]` and the value is `undefined` until the vault answers.

It adds no environment variables or scripts. `kitr add secure-storage` asks no questions, and no kit includes it. It is a client package, so a server-only project skips it with a warning. To preview the changes:

```sh
kitr add secure-storage --dry-run
```

`kitr remove secure-storage` removes the provider, the `packages` entry, the dependency, the `AGENTS.md` section and `config/secure-storage.ts`. It leaves `app/secure.ts` because you may have added items to it, and lists the files that still import `kitr/secure-storage`. Values already stored stay in the vault or in local storage.

## Configure

`kitr add` writes this file:

```ts
// config/secure-storage.ts
import { defineConfig } from 'kitr/secure-storage'

export default defineConfig({
  // OS vault on mobile/desktop; AES-GCM in the browser. true refuses the browser fallback.
  requireSecure: false,
})
```

| Option | Default | Description |
| --- | --- | --- |
| `requireSecure` | `false` | `true` makes every write throw when no vault is registered, instead of using the encrypted browser fallback. Reads and removes still work. |
| `prefix` | `'kitr:secure:'` | Put in front of every key, so `session` is stored as `kitr:secure:session`. Two apps on one origin need different prefixes. |
| `driver` | registered, else the browser fallback | A `SecureStorageDriver` that replaces the one the service would pick. For tests and custom vaults. |
| `storage` | the app's local storage driver | Where the browser fallback keeps its ciphertext. Any [Storage](/packages/storage) `StorageDriver`. |

The service picks its driver in this order: `driver` from the config, a driver a provider registered under `secure-storage`, then the browser fallback in a browser, or a memory driver on the server.

A stricter setup for a banking-grade desktop build:

```ts
// config/secure-storage.ts
import { defineConfig } from 'kitr/secure-storage'

export default defineConfig({
  prefix: 'acme:secure:',
  requireSecure: import.meta.env.PROD,
})
```

## Store your first secret

`kitr add` writes one typed item. An item names a key and the type of what is stored under it:

```ts
// app/secure.ts
import { defineSecureItem } from 'kitr/secure-storage'

/** Secrets, typed once: `useSecureItem(sessionItem)` in components, `sessionItem(storage).get()` elsewhere. */
export const sessionItem = defineSecureItem<{ token: string; expiresAt: number }>('session')
```

Read and write it in a component with `useSecureItem`:

```tsx
// app/features/account/session-status.tsx
import { useSecureItem } from 'kitr/secure-storage/react'
import { sessionItem } from '#app/secure'

export function SessionStatus() {
  const [session, setSession, { loading, secure }] = useSecureItem(sessionItem)
  if (loading) return null
  if (!session)
    return (
      <button
        type="button"
        onClick={() => setSession({ token: 'tok_ada_7f3k', expiresAt: Date.now() + 3_600_000 })}
      >
        Sign in as Ada
      </button>
    )
  return (
    <p>
      Signed in{secure ? '' : ' (browser storage)'}.{' '}
      <button type="button" onClick={() => setSession(undefined)}>
        Sign out
      </button>
    </p>
  )
}
```

Click **Sign in as Ada** and reload: the component renders nothing for a moment, then "Signed in (browser storage)." In DevTools, `localStorage` holds `kitr:secure:session` with a value like `pV0q3m8nVJ2xY1aB.Zk9…`, which is the IV and the ciphertext, not the token. **Sign out** removes it.

## Read and write a secret in a component

`useSecureItem(item)` returns a tuple:

| Position | Value |
| --- | --- |
| `[0]` | The stored value, or `undefined` while loading, when nothing is stored, and always on the server. |
| `[1]` | `set(value)`: stores `value`; `set(undefined)` removes it. Resolves when written. |
| `[2].loading` | `true` until the first read finishes. |
| `[2].secure` | `true` when an OS vault holds the value, `false` for the browser fallback and memory. |

Render nothing (or a skeleton) while `loading` is `true`. Don't treat `undefined` as "signed out" before then, or Ada sees a sign-in screen flash on every reload.

Each `useSecureItem` call binds its own copy of the item, and only that copy hears its writes. Two components that each call `useSecureItem(sessionItem)` don't update each other: when one signs out, the other keeps showing the old value until it remounts. Read the session in one component near the top and pass it down, or put it in a React context.

To act after the write, await `set`:

```tsx
// app/features/account/sign-in-form.tsx
import { useSecureItem } from 'kitr/secure-storage/react'
import { useNavigate } from 'kitr/router'
import { sessionItem } from '#app/secure'

export function SignInForm() {
  const [, setSession] = useSecureItem(sessionItem)
  const navigate = useNavigate()
  async function onSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault()
    const form = new FormData(event.currentTarget)
    const response = await fetch('/api/auth/sign-in', { method: 'POST', body: form })
    const { token, expiresIn } = (await response.json()) as { token: string; expiresIn: number }
    await setSession({ token, expiresAt: Date.now() + expiresIn * 1000 })
    await navigate({ to: '/orders' })
  }
  return (
    <form onSubmit={onSubmit}>
      <input name="email" type="email" defaultValue="ada@acme.com" />
      <input name="password" type="password" />
      <button type="submit">Sign in</button>
    </form>
  )
}
```

## Validate what comes back

Pass a `schema` to check the stored value on every read. Any [Standard Schema](https://standardschema.dev) library works, such as Zod. A value that fails is removed and reads as `undefined`:

```ts
// app/secure.ts
import { defineSecureItem } from 'kitr/secure-storage'
import { z } from 'zod'

export const sessionItem = defineSecureItem('session', {
  schema: z.object({ token: z.string(), expiresAt: z.number() }),
})
```

The type comes from the schema, so no type argument is needed. When version 2 of the app stores `{ token, refreshToken, expiresAt }` and Grace still has the old shape, or a value was corrupted, she reads `undefined` and signs in again instead of the app crashing on a missing field. A value that isn't valid JSON is removed the same way, with or without a schema.

Validation runs on reads only. `set` stores whatever you pass, so TypeScript is what checks writes.

## Store values that aren't JSON

Items serialise with `JSON.stringify` and `JSON.parse` by default. Pass a `codec` for anything else, such as a `Date` that should come back as a `Date`:

```ts
// app/secure.ts
import { defineSecureItem } from 'kitr/secure-storage'

export const lastUnlockItem = defineSecureItem<Date>('last-unlock', {
  codec: {
    encode: (date) => String(date.getTime()),
    decode: (raw) => new Date(Number(raw)),
  },
})
```

`lastUnlockItem(storage).set(new Date())` stores `'1767225600000'`, and `get()` returns a `Date`. A `decode` that throws counts as a corrupt value: it is removed and reads as `undefined`.

## Use secrets outside React

An item is a function that binds it to a `SecureStorage` service. Get the service from the app's container, or with `useSecureStorage(app)` from `kitr/secure-storage`:

```ts
// app/features/account/session.ts
import type { KitrApp } from 'kitr/app'
import { useSecureStorage } from 'kitr/secure-storage'
import { sessionItem } from '#app/secure'

export async function currentToken(app: KitrApp): Promise<string | null> {
  const storage = useSecureStorage(app) // same as app.container.use('secureStorage')
  const session = await sessionItem(storage).get()
  // => { token: 'tok_ada_7f3k', expiresAt: 1767229200000 }, or undefined
  if (!session || session.expiresAt < Date.now()) return null
  return session.token
}
```

A bound item has `key`, `get()`, `set(value)`, `remove()` and `subscribe(listener)`. `subscribe` calls the listener with the new value (or `undefined` after `remove`) on writes made through that bound item, and returns an unsubscribe function:

```ts
// app/features/account/watch-session.ts
import type { SecureStorage } from 'kitr/secure-storage'
import { sessionItem } from '#app/secure'

export function watchSession(storage: SecureStorage, onSignOut: () => void) {
  const session = sessionItem(storage)
  const off = session.subscribe((value) => {
    if (value === undefined) onSignOut()
  })
  return { session, off }
}
```

Make writes through the returned `session` so the listener hears them. In a component, `useSecureStorage()` from `kitr/secure-storage/react` returns the same service.

## Use the key-value API

Under the items is a plain async key-value API of strings. Use it for secrets you don't type ahead, such as one API key per integration:

```ts
// app/features/integrations/api-keys.ts
import type { SecureStorage } from 'kitr/secure-storage'

export async function saveIntegrationKey(storage: SecureStorage, integration: string, key: string) {
  await storage.set(`integration:${integration}`, key)
}

export async function listIntegrations(storage: SecureStorage) {
  const keys = await storage.keys()
  // => ['session', 'integration:stripe', 'integration:github']
  return keys.filter((k) => k.startsWith('integration:')).map((k) => k.slice('integration:'.length))
}

export async function readIntegrationKey(storage: SecureStorage, integration: string) {
  return storage.get(`integration:${integration}`)
  // => 'sk_live_…', or null when not stored
}
```

| Method | Description |
| --- | --- |
| `get(key)` | Resolves to the string, or `null`. |
| `set(key, value)` | Stores a string. Throws under `requireSecure` without a vault. |
| `remove(key)` | Deletes it. |
| `keys()` | Keys under this service's prefix, without the prefix. When the driver can't list keys, the keys written since the app started. |
| `clear()` | Removes every key `keys()` returns. |

Keys are given without the prefix; the service adds it.

## Clear secrets on sign-out

`clear()` removes everything this app stored under its prefix and leaves other apps' entries alone. Call it when Ada signs out, so Linus doesn't inherit her tokens on a shared machine:

```ts
// app/features/account/sign-out.ts
import type { SecureStorage } from 'kitr/secure-storage'

export async function signOut(storage: SecureStorage) {
  await fetch('/api/auth/sign-out', { method: 'POST' })
  await storage.clear()
}
```

To remove one secret, use the item's `remove()` or `set(undefined)` from the hook.

## Refuse the browser fallback

Set `requireSecure: true` when a secret must never be stored outside an OS vault. With no vault registered, writes throw and nothing is stored:

```ts
// app/features/account/remember-device.ts
import type { SecureStorage } from 'kitr/secure-storage'

export async function rememberDevice(storage: SecureStorage, deviceToken: string) {
  if (!storage.secure) return false
  await storage.set('device', deviceToken)
  return true
  // without the check, under requireSecure:
  // throws Error: kitr/secure-storage: no secure vault on this platform (requireSecure is on)
}
```

Reads and removes still work, so a value written before you turned it on can be read once and deleted. Check `storage.secure` before showing a "Remember this device" option, rather than catching the error.

## How the browser fallback works

In the browser, and in a shell with no vault registered, each value is encrypted before it is stored:

- On first use the driver creates a 256-bit AES-GCM key with `extractable: false` and keeps it in IndexedDB (`kitr-secure-storage`). Script can use the key but cannot read its bytes.
- Every write uses a fresh 12-byte IV and stores `<iv>.<ciphertext>` in base64 in local storage.
- The storage key is authenticated with each value, so ciphertext copied from `kitr:secure:refresh` to `kitr:secure:session` fails to decrypt.
- A value that fails to decrypt (tampered, moved, or written under another browser profile's key) is removed and reads as `null`.
- When two tabs start at once, both end up with the same key.

The key and the ciphertext live in the same browser profile, so the fallback stops a copied `localStorage` dump or a casual look in DevTools. It does not stop code running on your own page.

> **Warning**
> On the web, any script running on `app.acme.com` can call `secureStorage.get('session')` and read the token. The fallback is not protection against XSS. Keep untrusted scripts off pages that hold secrets, and prefer short-lived tokens. `secure` is `false` for this fallback, so you can tell.

Clearing site data deletes the key, and every stored value then reads as `null`. Treat secrets in the fallback as something the person may lose.

`createWebSecureStorageDriver(storage)` builds the fallback yourself, over any [Storage](/packages/storage) driver. Without Web Crypto, its first write rejects with `kitr/secure-storage: Web Crypto is not available`.

## Use it on the server

On the server the service is an in-memory store, so code shared with the client runs without an environment check: reads resolve to `null` and items to `undefined`.

> **Warning**
> The server store is one map for the whole process, shared by every request and lost on restart. Never write a person's secret to it during a request: the next request, from anyone, can read it. Keep server secrets in environment variables and per-user tokens in your database or session.

## Where values are kept

| Where it runs | Driver | `secure` |
| --- | --- | --- |
| Browser | `createWebSecureStorageDriver()`: AES-GCM, ciphertext in local storage | `false` |
| Desktop and mobile shells | The same fallback inside the webview, unless a provider registers a vault. The ciphertext goes to the shell's storage driver when one is registered. | `false` |
| A registered vault | Whatever the driver wraps, such as Electron `safeStorage` | `true` when the driver says so |
| Server | `createMemorySecureStorageDriver()`, in memory | `false` |

Today [Desktop](/packages/desktop) and [Mobile](/packages/mobile) register only `platform` and `storage` drivers, not `secure-storage`. To keep secrets in the Keychain, the Keystore or Electron's `safeStorage`, register a vault driver as shown under [Extend](#extend). When the [Devtools](/packages/devtools) provider is installed, the service logs which driver is active at boot (for example `web-crypto (encrypted web fallback)`) and each key set or removed, never the values.

## Errors

| Error | When | What to do |
| --- | --- | --- |
| `kitr/secure-storage: no secure vault on this platform (requireSecure is on)` | `set()` under `requireSecure: true` with no vault. | Check `storage.secure` first, or register a vault driver. |
| `kitr/secure-storage: Web Crypto is not available` | The browser fallback's first use, without `crypto.subtle` (a plain `http://` page other than `localhost`). | Serve the app over HTTPS. |
| `kitr/secure-storage: could not store the encryption key` | IndexedDB refused the new key and holds none. | Rare; usually storage is full or blocked in a private window. |

A value that fails to decrypt, parse or validate is not an error: it is removed and reads as missing.

## Testing

`createMemorySecureStorageDriver(name)` keeps values in a `Map`. Its `secure` is `false`; spread it and set `secure: true` to test code that checks for a vault. Pass it through `config['secure-storage'].driver`:

```tsx
// app/features/account/session-status.test.tsx
import { fireEvent, screen } from '@testing-library/react'
import { createMemorySecureStorageDriver } from 'kitr/secure-storage'
import { secureStorageProvider } from 'kitr/secure-storage/provider'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { describe, expect, it } from 'vitest'
import { sessionItem } from '#app/secure'
import { SessionStatus } from './session-status'

async function setup(secure = false) {
  const driver = { ...createMemorySecureStorageDriver('vault'), secure }
  const app = await createTestApp({
    providers: [secureStorageProvider],
    config: { 'secure-storage': { driver } },
  })
  return { app, driver, storage: app.container.use('secureStorage') }
}

describe('session status', () => {
  it('stores the session under the prefixed key and clears it on sign-out', async () => {
    const { app, driver } = await setup()
    renderWithKitr(<SessionStatus />, { app })
    fireEvent.click(await screen.findByRole('button', { name: 'Sign in as Ada' }))
    await screen.findByText(/Signed in \(browser storage\)/)
    expect(JSON.parse((await driver.get('kitr:secure:session'))!)).toMatchObject({
      token: 'tok_ada_7f3k',
    })
    fireEvent.click(screen.getByRole('button', { name: 'Sign out' }))
    await screen.findByRole('button', { name: 'Sign in as Ada' })
    expect(await driver.get('kitr:secure:session')).toBeNull()
  })

  it('reads an existing session from the vault', async () => {
    const { app, storage } = await setup(true)
    await sessionItem(storage).set({ token: 'tok_grace_2m9q', expiresAt: Date.now() + 60_000 })
    renderWithKitr(<SessionStatus />, { app })
    await screen.findByText('Signed in.')
  })

  it('refuses to write without a vault under requireSecure', async () => {
    const app = await createTestApp({
      providers: [secureStorageProvider],
      config: {
        'secure-storage': { driver: createMemorySecureStorageDriver(), requireSecure: true },
      },
    })
    const storage = app.container.use('secureStorage')
    await expect(storage.set('session', 'tok_ada_7f3k')).rejects.toThrow(/requireSecure is on/)
  })
})
```

For code that takes the service directly, `createSecureStorage({ driver: createMemorySecureStorageDriver() })` needs no app. To test the browser fallback itself, give `createWebSecureStorageDriver()` a memory [Storage](/packages/storage) driver and check the stored value holds no plain text; Node 20 and later have Web Crypto, and without IndexedDB the key lives in memory.

## Extend

A vault implements `SecureStorageDriver`. Keys arrive with the prefix already added:

```ts
interface SecureStorageDriver {
  name: string
  secure: boolean // true when an OS vault or hardware holds the values
  get(key: string): Promise<string | null>
  set(key: string, value: string): Promise<void>
  remove(key: string): Promise<void>
  keys?(): Promise<string[]> // optional: without it, keys() lists what was written this session
}
```

This driver keeps secrets in Electron's [`safeStorage`](https://www.electronjs.org/docs/latest/api/safe-storage), which encrypts with the macOS Keychain, Windows DPAPI or the Linux secret store. The main process encrypts and writes a file in the app's data folder; the renderer reaches it over the IPC bridge the desktop platform sets up:

```ts
// platforms/app/main.ts
import { readFile, writeFile } from 'node:fs/promises'
import { join } from 'node:path'
import { app, ipcMain, safeStorage } from 'electron'
import { handleIpc } from 'kitr/desktop/electron-main'

const vaultFile = () => join(app.getPath('userData'), 'vault.json')
const load = async (): Promise<Record<string, string>> =>
  JSON.parse(await readFile(vaultFile(), 'utf8').catch(() => '{}'))
const save = (data: Record<string, string>) => writeFile(vaultFile(), JSON.stringify(data))

handleIpc<{
  'vault.get': (key: string) => string | null
  'vault.set': (key: string, value: string) => void
  'vault.remove': (key: string) => void
  'vault.keys': () => string[]
}>(ipcMain, {
  'vault.get': async (_event, key) => {
    const sealed = (await load())[key]
    return sealed ? safeStorage.decryptString(Buffer.from(sealed, 'base64')) : null
  },
  'vault.set': async (_event, key, value) => {
    const data = await load()
    data[key] = safeStorage.encryptString(value).toString('base64')
    await save(data)
  },
  'vault.remove': async (_event, key) => {
    const data = await load()
    delete data[key]
    await save(data)
  },
  'vault.keys': async () => Object.keys(await load()),
})
// ...
```

```ts
// app/providers/vault_provider.ts
import { defineProvider } from 'kitr/app'
import { createIpcClient } from 'kitr/desktop/electron'
import type { SecureStorageDriver } from 'kitr/secure-storage'

const ipc = createIpcClient<{
  'vault.get': (key: string) => string | null
  'vault.set': (key: string, value: string) => void
  'vault.remove': (key: string) => void
  'vault.keys': () => string[]
}>()

function electronVault(): SecureStorageDriver {
  return {
    name: 'electron-safe-storage',
    secure: true,
    get: (key) => ipc.invoke('vault.get', key),
    set: (key, value) => ipc.invoke('vault.set', key, value),
    remove: (key) => ipc.invoke('vault.remove', key),
    keys: () => ipc.invoke('vault.keys'),
  }
}

export default defineProvider({
  name: 'vault',
  register(app) {
    if (ipc.available) app.drivers.register('secure-storage', electronVault(), { platform: 'desktop' })
  },
})
```

Create the provider with `kitr make:provider vault` and add `() => import('#app/providers/vault_provider')` to `providers` in `kitrrc.ts`. Inside the Electron app, `secureStorage.secure` is now `true`, the session status drops "(browser storage)", and `requireSecure: true` lets writes through. In the web build `ipc.available` is `false`, so the browser fallback still applies.

On Linux without a secret store, `safeStorage` falls back to a hard-coded password; check `safeStorage.getSelectedStorageBackend()` in main if that matters to you. In a Tauri app the same driver shape fits over a keyring plugin through Tauri commands. The `SecureStorageDriver` and `SecureItem` types are in the [API reference](/packages/secure-storage/api).

## Next steps

- [API reference](/packages/secure-storage/api)
- [Storage](/packages/storage): synchronous items for values that aren't secret, and the driver the fallback writes to.
- [Auth](/packages/auth): sign-in, sessions and the token adapter.
- [Electron safeStorage](https://www.electronjs.org/docs/latest/api/safe-storage): what each operating system uses underneath.
- [SubtleCrypto on MDN](https://developer.mozilla.org/docs/Web/API/SubtleCrypto): the Web Crypto API behind the browser fallback.


# SEO API

Source: https://kitr.dev/packages/seo/api

Every export of `kitr/seo`, read from the published type definitions. The [guide](/packages/seo) shows them in use.

## kitr/seo

### cacheHeaders

```ts
function cacheHeaders(options?: {
  maxAge?: number;
  sMaxAge?: number;
  staleWhileRevalidate?: number;
  private?: boolean;
}): {
  'cache-control': string;
};
```

A `cache-control` header for TanStack Start's `headers` route option:
`headers: () => cacheHeaders({ sMaxAge: 60 })`. Public unless `private` is set.

### jsonLd

```ts
function jsonLd(data: Record<string, unknown> & {
  '@type': string;
}): {
  type: string;
  children: string;
};
```

A JSON-LD script for `head().scripts`: `scripts: [jsonLd({ '@type': 'Article', headline })]`.

### robotsTxt

```ts
function robotsTxt(config: SeoConfig): string | null;
```

`robots.txt` text from the config, or null when `robots` is false. kitr does not write the file; serve or write it yourself.

### seo

```ts
function seo(input: SeoInput): {
  meta: Record<string, string>[];
  links: Record<string, string>[];
};
```

Meta tags for a route's `head()`: `head: () => seo({ title, description })`.
Covers title, description, Open Graph, Twitter cards, canonical and robots.

### ssrRoute

```ts
function ssrRoute(mode: boolean | 'data-only'): {
  readonly ssr: boolean | "data-only";
};
```

Route option presets. Spread into `createFileRoute(...)({ ...ssrRoute('data-only'), ... })`.

### defineConfig

```ts
const defineConfig: <const C extends SeoConfig>(config: C) => C;
```

Types the default export of `config/seo.ts`.

### SeoConfig

```ts
interface SeoConfig {
  /** Site-wide defaults for `seo()`. */
  site?: SeoSite;
  /** Intended default per-route rendering in `ssr` mode. Not read by kitr yet; use `ssrRoute()` per route. */
  ssr?: boolean | 'data-only';
  /** Routes to prerender at build time; `crawlLinks` follows links from them. A `static` web platform prerenders everything. */
  prerender?: string[] | {
    routes: string[];
    crawlLinks?: boolean;
  };
  /** Rules for `robotsTxt()`. `false` makes it return null. */
  robots?: false | {
    allow?: string[];
    disallow?: string[];
    sitemap?: boolean;
  };
}
```

Options for `config/seo.ts`. The build reads `prerender` and `site.url` from the file's source text.

### SeoInput

```ts
interface SeoInput {
  /** The page title, without the site name. */
  title?: string;
  /** The page summary for search results and share cards. */
  description?: string;
  /** Share image for this page; replaces `site.image`. Use an absolute URL. */
  image?: string;
  /** The page's canonical URL; falls back to `site.url`, so pass it on every page. */
  url?: string;
  /** `og:type`. Default `website`. */
  type?: 'website' | 'article' | 'product';
  /** Adds `robots: noindex, nofollow`. */
  noIndex?: boolean;
  /** Joined into a `keywords` meta tag. */
  keywords?: string[];
  /** Site defaults, usually `site` from `config/seo.ts`. `seo()` does not read the config itself. */
  site?: SeoSite;
}
```

What one page passes to `seo()`. Every field is optional; `site` supplies the defaults.

### SeoSite

```ts
interface SeoSite {
  /** Appended to page titles (`Pricing · Acme`) and sent as `og:site_name`. */
  name?: string;
  /** Canonical origin (`https://example.com`). Turns on the sitemap for prerendered routes. */
  url?: string;
  /** Share image for pages that set none. Use an absolute URL. */
  image?: string;
  /** The site's X (Twitter) handle, sent as `twitter:site`. */
  twitter?: string;
  /** Sent as `og:locale`, such as `en_US`. */
  locale?: string;
}
```

Site-wide values for `seo()` and the build: name, canonical origin, default image, handle and locale.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# SEO

Source: https://kitr.dev/packages/seo

Paste a link into Slack or search for your product, and what people see comes from a handful of tags: the title, the description, a share image, a canonical URL. `kitr/seo` writes those tags for a route from one call, `seo({ title, description })`, adds structured data for rich results, and tells the build which pages to prerender as plain HTML and where the sitemap lives. It builds on [TanStack Router's `head`](https://tanstack.com/router/latest/docs/framework/react/guide/document-head-management) and [TanStack Start's prerendering](https://tanstack.com/start/latest/docs/framework/react/guide/static-prerendering); kitr adds the tag set, the site defaults and the build wiring.

The examples on this page follow one scenario: Acme's marketing site at `acme.com` has a pricing page, a blog with posts by Ada and Grace, and a sign-in link to the app at `app.acme.com`, which search engines should not index.

`kitr/seo` runs on both sides: `seo()` and the other helpers are plain functions that the server renders into HTML and the client keeps up to date while people navigate. Tags only help when the HTML reaches crawlers, so use a web platform in `ssr` or `static` mode for pages you want found. In an `spa` app, crawlers and link previews see the same empty shell for every URL.

## Install

```sh
kitr add seo
```

What `kitr add` does:

- Installs `@kitr/seo`.
- Adds `'@kitr/seo'` to `packages` in `kitrrc.ts`. There is no provider: nothing runs at startup.
- Writes `config/seo.ts` (shown in [Configure](#configure)) and regenerates `config/index.ts`.
- Adds a `## kitr: seo` section to `AGENTS.md` telling coding agents to set `head: () => seo({ title, description })` on routes, to add structured data with `jsonLd()`, and to use `ssrRoute()` and `cacheHeaders()` for rendering and CDN caching.

`kitr add seo` asks no questions and adds no env variables. To edit `package.json` without running the package manager, pass the global flag:

```sh
kitr add seo --no-install
```

The `fullstack`, `saas`, `site` and `realtime` kits include seo. The `site` kit writes its own `config/seo.ts` with a prerender list and a site URL, and sets `head` on every page. It is a client package, so in a server-only project `kitr add seo` prints a warning and skips it.

`kitr remove seo` removes the `packages` entry, the dependency and the `AGENTS.md` section, and deletes `config/seo.ts`. It leaves the `seo()` calls in your routes, which you delete by hand.

## Configure

`kitr add seo` writes this file, with `name` set to the `name` in your `package.json` (here `acme-site`):

```ts
// config/seo.ts
import { defineConfig } from 'kitr/seo'

export default defineConfig({
  site: { name: 'acme-site' },
  // Routes prerendered at build time by a web platform in ssr mode; a static web platform prerenders everything.
  prerender: [],
})
```

Fill in the rest of `site` before you launch:

```ts
// config/seo.ts
import { defineConfig } from 'kitr/seo'

export default defineConfig({
  site: {
    name: 'Acme',
    url: 'https://acme.com',
    image: 'https://acme.com/og/default.png',
    twitter: '@acme',
    locale: 'en_US',
  },
  prerender: { routes: ['/', '/pricing', '/blog'], crawlLinks: true },
  robots: { disallow: ['/api'] },
})
```

| Option | Default | Description |
| --- | --- | --- |
| `site.name` | none | Appended to page titles (`Pricing · Acme`) and sent as `og:site_name`. Also the title of a page that sets none. |
| `site.url` | none | The canonical origin, `https://acme.com`. Turns on the sitemap at build time and adds the `Sitemap:` line to `robotsTxt()`. Must be a string literal; see [Generate a sitemap](#generate-a-sitemap). |
| `site.image` | none | The share image for pages that set none. Use an absolute URL. |
| `site.twitter` | none | The site's X (Twitter) handle, sent as `twitter:site`. |
| `site.locale` | none | Sent as `og:locale`, such as `en_US`. |
| `prerender` | `[]` | Routes the build renders to HTML files. An array of paths, or `{ routes, crawlLinks }`. |
| `prerender.routes` | `[]` | The paths to prerender, such as `['/', '/pricing']`. |
| `prerender.crawlLinks` | `false` | Also prerender every page linked from those routes. |
| `robots` | `{}` | Rules for `robotsTxt()`. `false` makes it return `null`. |
| `robots.allow` | `['/']` | `Allow:` lines. |
| `robots.disallow` | `[]` | `Disallow:` lines. |
| `robots.sitemap` | `true` | Add `Sitemap: <site.url>/sitemap.xml` when `site.url` is set. |
| `ssr` | none | Declared in `SeoConfig`, but nothing reads it today. Set rendering per route with [`ssrRoute()`](#choose-how-a-route-renders). |

`seo()` does not read this file by itself. Pass `site` to it, as [Use your site defaults on every page](#use-your-site-defaults-on-every-page) shows. The build reads `prerender` and `site.url` from the file's source text, without running it, so both must be written out as literals.

## Give a page its title

Set `head` on a route and return `seo()` from it:

```tsx
// app/routes/pricing.tsx
import { createFileRoute } from '@tanstack/react-router'
import { seo } from 'kitr/seo'

export const Route = createFileRoute('/pricing')({
  head: () => seo({ title: 'Pricing', description: 'Plans for every team size.' }),
  component: PricingPage,
})

function PricingPage() {
  return <h1>Pricing</h1>
}
```

Open `/pricing` and view the page source. The root route's `<HeadContent />` renders the tags into `<head>`:

```html
<title>Pricing</title>
<meta property="og:title" content="Pricing">
<meta name="twitter:title" content="Pricing">
<meta name="description" content="Plans for every team size.">
<meta property="og:description" content="Plans for every team size.">
<meta name="twitter:description" content="Plans for every team size.">
<meta property="og:type" content="website">
<meta name="twitter:card" content="summary">
```

`seo()` returns `{ meta, links }`, the shape TanStack Router's `head` expects. When the visitor navigates to another page, the router swaps the tags for that page's.

## Use your site defaults on every page

To get the site name in every title and a default share image, pass `site`. Import it from `config/seo.ts` once, in a small helper:

```ts
// app/seo.ts
import { type SeoInput, seo } from 'kitr/seo'
import seoConfig from '#config/seo'

/** seo() with the site defaults from config/seo.ts. */
export function pageSeo(input: SeoInput) {
  return seo({ site: seoConfig.site, ...input })
}
```

Use it in routes, with the page's own URL:

```tsx
// app/routes/pricing.tsx
import { createFileRoute } from '@tanstack/react-router'
import { pageSeo } from '#app/seo'

export const Route = createFileRoute('/pricing')({
  head: () =>
    pageSeo({
      title: 'Pricing',
      description: 'Plans for every team size.',
      url: 'https://acme.com/pricing',
    }),
  component: PricingPage,
})

function PricingPage() {
  return <h1>Pricing</h1>
}
```

With the config from [Configure](#configure), the call returns:

```ts
// => meta:
// { title: 'Pricing · Acme' }
// { property: 'og:title', content: 'Pricing' }
// { name: 'twitter:title', content: 'Pricing' }
// { name: 'description', content: 'Plans for every team size.' }
// { property: 'og:description', content: 'Plans for every team size.' }
// { name: 'twitter:description', content: 'Plans for every team size.' }
// { property: 'og:type', content: 'website' }
// { property: 'og:site_name', content: 'Acme' }
// { property: 'og:locale', content: 'en_US' }
// { property: 'og:url', content: 'https://acme.com/pricing' }
// { property: 'og:image', content: 'https://acme.com/og/default.png' }
// { name: 'twitter:image', content: 'https://acme.com/og/default.png' }
// { name: 'twitter:card', content: 'summary_large_image' }
// { name: 'twitter:site', content: '@acme' }
// => links:
// { rel: 'canonical', href: 'https://acme.com/pricing' }
```

How the values combine:

| Tag | Comes from |
| --- | --- |
| `<title>` | `title · site.name`; `title` alone when it equals `site.name`; `site.name` when there is no `title`. |
| `og:title`, `twitter:title` | `title` without the site name. |
| `description`, `og:description`, `twitter:description` | `description`, only when set. |
| `og:url`, canonical link | `url`, else `site.url`. |
| `og:image`, `twitter:image` | `image`, else `site.image`. |
| `twitter:card` | `summary_large_image` when there is an image, else `summary`. |
| `og:type` | `type`, default `'website'`. |

Always pass `url` for a page when `site` has a `url`. Without it, `og:url` and the canonical link fall back to `site.url`, so the page tells search engines it is a copy of your home page and they may drop it from results.

## Set defaults in the root route

Tags from the root route apply to every page. A child route's `<title>` and its tags with the same `name` or `property` replace the root's, so put the site-wide description in the root and let pages override it:

```tsx
// app/routes/__root.tsx
import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from 'kitr/router'
import type { KitrRouterContext } from 'kitr/router'
import { pageSeo } from '#app/seo'

export const Route = createRootRouteWithContext<KitrRouterContext>()({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      ...pageSeo({ description: 'Acme keeps your team’s projects, orders and invoices in one place.' }).meta,
    ],
  }),
  component: RootDocument,
})

function RootDocument() {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}
```

Spread only `.meta` in the root. TanStack Router merges `links` from every matched route without removing duplicates, so a canonical link in the root plus one in the page gives the page two canonical URLs.

## Add a share image

Chat apps and social networks show `og:image` as a large card. Pass an absolute URL; most crawlers do not resolve `/og/pricing.png` against your domain:

```tsx
// app/routes/pricing.tsx
import { createFileRoute } from '@tanstack/react-router'
import { pageSeo } from '#app/seo'

export const Route = createFileRoute('/pricing')({
  head: () =>
    pageSeo({
      title: 'Pricing',
      description: 'Plans for every team size.',
      url: 'https://acme.com/pricing',
      image: 'https://acme.com/og/pricing.png',
    }),
  component: () => <h1>Pricing</h1>,
})
```

The page image replaces `site.image` in `og:image` and `twitter:image`, and `twitter:card` becomes `summary_large_image`. A 1200 × 630 PNG or JPEG works everywhere. Check the result with a preview tool such as [opengraph.xyz](https://www.opengraph.xyz) after you deploy.

## Describe an article

For a blog post, read the post in the loader and build the tags from `loaderData`. Set `type: 'article'`:

```tsx
// app/routes/blog/$slug.tsx
import { createFileRoute } from '@tanstack/react-router'
import { notFound } from 'kitr/router'
import { getPost } from '#app/content/posts'
import { pageSeo } from '#app/seo'

export const Route = createFileRoute('/blog/$slug')({
  loader: ({ params }) => {
    const post = getPost(params.slug)
    if (!post) throw notFound()
    return post
  },
  head: ({ loaderData, params }) =>
    pageSeo({
      title: loaderData?.title,
      description: loaderData?.excerpt,
      url: `https://acme.com/blog/${params.slug}`,
      type: 'article',
      keywords: loaderData?.tags,
    }),
  component: PostPage,
})

function PostPage() {
  const post = Route.useLoaderData()
  return <h1>{post.title}</h1>
}
```

For Grace's post "Invoices in one click", the page gets `<title>Invoices in one click · Acme</title>`, `og:type` `article`, and a `keywords` tag joined with commas (`invoices, billing`). Search engines ignore `keywords`; it only helps your own site search. `head` runs after the loader, on the server for the first request and on the client after each navigation.

## Keep a page out of search results

Sign-in pages, drafts and anything behind a login should not show up in search. Pass `noIndex: true`:

```tsx
// app/routes/sign-in.tsx
import { createFileRoute } from '@tanstack/react-router'
import { pageSeo } from '#app/seo'

export const Route = createFileRoute('/sign-in')({
  head: () => pageSeo({ title: 'Sign in', url: 'https://acme.com/sign-in', noIndex: true }),
  component: () => <h1>Sign in to Acme</h1>,
})
```

The page gets `<meta name="robots" content="noindex, nofollow">`. Crawlers must be able to load the page to see that tag, so don't also block it in `robots.txt`. To keep a whole area out, such as `/app`, set `noIndex` in its layout route's `head`; its pages inherit the tag unless they set their own `robots` meta.

## Add structured data

Structured data tells search engines what a page is about: an organization, an article, a product with a price. `jsonLd()` turns a [schema.org](https://schema.org) object into a `<script type="application/ld+json">` for `head().scripts`, and adds `@context` for you:

```tsx
// app/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { jsonLd } from 'kitr/seo'
import { pageSeo } from '#app/seo'

export const Route = createFileRoute('/')({
  head: () => ({
    ...pageSeo({ title: 'Acme', url: 'https://acme.com' }),
    scripts: [
      jsonLd({
        '@type': 'Organization',
        name: 'Acme',
        url: 'https://acme.com',
        logo: 'https://acme.com/logo.png',
      }),
    ],
  }),
  component: () => <h1>Acme</h1>,
})
```

`jsonLd()` returns:

```ts
// => {
//   type: 'application/ld+json',
//   children: '{"@context":"https://schema.org","@type":"Organization","name":"Acme","url":"https://acme.com","logo":"https://acme.com/logo.png"}',
// }
```

Test the page with Google's [Rich Results Test](https://search.google.com/test/rich-results) to see which result types it qualifies for.

> **Warning**
> `jsonLd()` puts `JSON.stringify` output inside a `<script>` tag without escaping it. If a value comes from users, such as a post title or a review, a `</script>` in it ends the tag early and the rest runs as HTML. For user content, use TanStack Router's own form, `meta: [{ 'script:ld+json': { '@context': 'https://schema.org', '@type': 'Article', headline: post.title } }]`, which escapes the JSON.

## Prerender pages at build time

Pages that are the same for every visitor, such as the home page, pricing and the blog, can be built once into HTML files and served from a CDN. List them in `prerender`:

```ts
// config/seo.ts
import { defineConfig } from 'kitr/seo'

export default defineConfig({
  site: { name: 'Acme', url: 'https://acme.com' },
  prerender: { routes: ['/', '/pricing', '/blog'], crawlLinks: true },
})
```

Then build the web platform:

```sh
kitr build site
```

The `kitr()` Vite plugin reads the list and passes it to TanStack Start, which renders each route to `index.html` in its own folder (`/pricing/index.html`). With `crawlLinks: true` it also follows every link on those pages, so each blog post linked from `/blog` is prerendered too. Pages not reached this way keep rendering on the server per request.

What the build does with `prerender` in each web mode:

| Web mode | Effect |
| --- | --- |
| `ssr` | Prerenders the listed routes (and the pages they link to, with `crawlLinks`). Everything else renders on the server. |
| `static` | Prerenders every page. An empty list starts from `/` and crawls every link. A non-empty list starts from `/` plus those routes, and follows links only with `crawlLinks: true`. |
| `spa` | Ignored. The build writes one HTML shell. |

The build reads `config/seo.ts` as text, without running it. A list built in code (`prerender: posts.map(...)`) or imported from another file is not seen. Write each path as a string, or list a page that links to all of them and set `crawlLinks: true`.

## Generate a sitemap

Set `site.url` to a string literal and the build turns on [TanStack Start's sitemap](https://tanstack.com/start/latest/docs/framework/react/guide/static-prerendering), with `https://acme.com` as its host:

```ts
// config/seo.ts
import { defineConfig } from 'kitr/seo'

export default defineConfig({
  site: { name: 'Acme', url: 'https://acme.com' },
  prerender: { routes: ['/', '/pricing', '/blog'], crawlLinks: true },
})
```

Start writes `sitemap.xml` into the build output from the pages it knows about at build time, which are the ones it prerenders. Pages that only render on the server per request are not in it, so prerender (or crawl to) every page you want listed. `robotsTxt()` points crawlers at `<site.url>/sitemap.xml`.

Don't read the URL from an env variable here (`url: process.env.SITE_URL`). The build finds `site.url` by matching the source text, so only a quoted string turns the sitemap on.

## Write robots.txt

`robotsTxt(config)` returns the text of a `robots.txt` built from `robots` and `site.url`:

```ts
import { robotsTxt } from 'kitr/seo'

robotsTxt({ site: { url: 'https://acme.com' }, robots: { disallow: ['/app', '/api'] } })
// => 'User-agent: *\nAllow: /\nDisallow: /app\nDisallow: /api\n\nSitemap: https://acme.com/sitemap.xml\n'
```

kitr does not write the file for you today. Add a small Vite plugin that writes it to `public/` when the build starts, so Vite copies it into the output with your other static files:

```ts
// vite.config.ts
import { writeFileSync } from 'node:fs'
import { kitr } from 'kitr/vite'
import { robotsTxt } from 'kitr/seo'
import { defineConfig } from 'vite'
import seoConfig from './config/seo'

export default defineConfig({
  plugins: [
    kitr(),
    {
      name: 'acme-robots',
      buildStart() {
        const text = robotsTxt(seoConfig)
        if (text) writeFileSync('public/robots.txt', text)
      },
    },
  ],
})
```

With `robots: false`, `robotsTxt()` returns `null` and the plugin writes nothing. Add `public/robots.txt` to `.gitignore` if you only want the generated copy.

## Choose how a route renders

In a web platform in `ssr` mode, every route renders on the server by default. `ssrRoute()` returns the route option that changes that. Spread it into the route:

```tsx
// app/routes/_app/reports.tsx
import { createFileRoute } from '@tanstack/react-router'
import { ssrRoute } from 'kitr/seo'

export const Route = createFileRoute('/_app/reports')({
  ...ssrRoute('data-only'),
  loader: async () => {
    const response = await fetch('https://app.acme.com/api/reports/invoices')
    return (await response.json()) as Array<{ month: string; total: number }>
  },
  component: ReportsPage,
})

function ReportsPage() {
  const rows = Route.useLoaderData()
  return <p>{rows.length} months of invoices</p>
}
```

| Call | Returns | The route |
| --- | --- | --- |
| `ssrRoute(true)` | `{ ssr: true }` | Renders on the server. The default. |
| `ssrRoute('data-only')` | `{ ssr: 'data-only' }` | Runs the loader on the server, renders in the browser. For heavy charts that crawlers don't need. |
| `ssrRoute(false)` | `{ ssr: false }` | Loads and renders in the browser only. For pages that need `window`. |

A route that does not render on the server sends no page content to crawlers. Keep `ssr: true` on anything you want found. See TanStack Start's [selective SSR](https://tanstack.com/start/latest/docs/framework/react/guide/selective-ssr) for how it combines with parent routes.

## Cache pages at the CDN

`cacheHeaders()` builds a `cache-control` header for TanStack Start's `headers` route option:

```tsx
// app/routes/blog/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { cacheHeaders } from 'kitr/seo'
import { pageSeo } from '#app/seo'

export const Route = createFileRoute('/blog/')({
  headers: () => cacheHeaders({ sMaxAge: 60, staleWhileRevalidate: 300 }),
  head: () => pageSeo({ title: 'Blog', url: 'https://acme.com/blog' }),
  component: () => <h1>Blog</h1>,
})
```

```ts
// => { 'cache-control': 'public, s-maxage=60, stale-while-revalidate=300' }
```

| Option | Adds |
| --- | --- |
| `maxAge` | `max-age=<seconds>`: how long browsers keep it. |
| `sMaxAge` | `s-maxage=<seconds>`: how long CDNs and shared caches keep it. |
| `staleWhileRevalidate` | `stale-while-revalidate=<seconds>`: how long a cache may serve the old copy while fetching a new one. |
| `private` | Starts with `private` instead of `public`, so shared caches don't store it. |

With no options it returns `{ 'cache-control': 'public' }`. For a page that shows the signed-in user, such as Ada's orders, use `cacheHeaders({ private: true, maxAge: 0 })` (`private, max-age=0`); a `public` header there could let a CDN serve Ada's page to Linus. See [MDN on Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).

## Testing

`seo()` is a plain function, so test what your pages put in `head` without rendering anything. Test the `pageSeo()` helper once, and assert on the tags your pages depend on:

```ts
// app/seo.test.ts
import { robotsTxt } from 'kitr/seo'
import { describe, expect, it } from 'vitest'
import seoConfig from '#config/seo'
import { pageSeo } from './seo'

describe('pageSeo', () => {
  it('adds the site name and the canonical URL', () => {
    const { meta, links } = pageSeo({
      title: 'Pricing',
      description: 'Plans for every team size.',
      url: 'https://acme.com/pricing',
    })
    expect(meta).toContainEqual({ title: 'Pricing · Acme' })
    expect(meta).toContainEqual({ property: 'og:title', content: 'Pricing' })
    expect(meta).toContainEqual({ name: 'twitter:card', content: 'summary_large_image' })
    expect(links).toEqual([{ rel: 'canonical', href: 'https://acme.com/pricing' }])
  })

  it('keeps the sign-in page out of search results', () => {
    const { meta } = pageSeo({ title: 'Sign in', url: 'https://acme.com/sign-in', noIndex: true })
    expect(meta).toContainEqual({ name: 'robots', content: 'noindex, nofollow' })
  })

  it('points crawlers at the sitemap', () => {
    expect(robotsTxt(seoConfig)).toContain('Sitemap: https://acme.com/sitemap.xml')
  })
})
```

The test runs in Node; there is no app to boot and nothing to fake. The `#config` and `#app` aliases come from the `kitr()` Vite plugin, which your `vitest.config.ts` uses. To check the final HTML of a prerendered page, run `kitr build site` and read `/pricing/index.html` from the build output in an end-to-end test.

## Next steps

- [API reference](/packages/seo/api) for every export and type.
- [Web](/packages/web) for the `ssr`, `static` and `spa` modes that decide what crawlers see.
- [Router](/packages/router) for routes, loaders and `notFound()`.
- [TanStack Router document head management](https://tanstack.com/router/latest/docs/framework/react/guide/document-head-management) for how `head` tags merge.
- [Google Search Central](https://developers.google.com/search/docs) for how search engines use these tags.


# Server API

Source: https://kitr.dev/packages/server/api

## createServer

```ts
function createServer(options?: {
  providers?: ProviderInput[] // usually rc.providers
  config?: Record<string, unknown> // per-package config, keyed by package
  env?: Record<string, unknown>    // validated env from createEnv, exposed as app.env
  server?: ServerConfig           // shortcut for config.server
  app?: KitrApp                   // reuse an app you created
  logger?: Logger
}): KitrServer
```

## KitrServer

| Member | Description |
| --- | --- |
| `listen({ port?, host? })` | Boot, start a standalone server and run providers' `ready`. Resolves to `{ url, close() }`. Handles `SIGINT` and `SIGTERM`. |
| `fetch(request)` | Web-standard handler. Boots on first call. |
| `boot()` | Run `register` and `boot` for every provider. |
| `close()` | Run providers' `shutdown`. |
| `mount(base, handler)` | Mount an h3 app or anything with `fetch` under a path. |
| `use(middleware)` | Add h3 middleware. |
| `app` | The kitr app: `container`, `config`, lifecycle. |
| `h3` | The underlying h3 instance. |
| `logger` | The root logger. |
| `config` | Resolved server config. |

## Request context

```ts
useRequest(): RequestContext          // throws outside a request
tryUseRequest(): RequestContext | undefined
useRequestApp(fallback?): KitrApp     // the request's container fork
runWithRequest(ctx, fn)               // for custom adapters

interface RequestContext {
  event: H3Event
  app: KitrApp
  requestId: string
  logger: Logger
  startedAt: number
  locals: Record<string, unknown>
}
```

## Errors

```ts
errorToResponse(error, event?): Response
normaliseServerError(error): KitrError
```

## defineConfig

```ts
defineConfig(config: ServerConfig): ServerConfig
```

See [the options table](/packages/server#configuration).


# Server

Source: https://kitr.dev/packages/server

API routes, webhooks from a payment provider, a realtime channel for order updates: anything that runs outside the browser needs a server underneath. `kitr/server` is that server. It boots your providers in order, gives every request an id and a logger, turns thrown errors into clean JSON, and waits for in-flight requests before it shuts down.

It is built on [h3](https://h3.dev) and served by [srvx](https://srvx.h3.dev), so the same server runs on Node, Bun, Deno and Cloudflare Workers, standalone or inside TanStack Start. It never imports React, so a pure backend built with kitr ships none.

`kitr/server` runs on the server only. It is also a platform: `server()` in `kitrrc.ts` tells `kitr dev`, `kitr build` and `kitr start` how to run it. To define routes and controllers on top of it, add [API routes](/packages/api); for functions your own React UI calls, use [Actions](/packages/actions).

The examples on this page build the Acme order service at `app.acme.com`: a server that answers `/api/orders`, logs each request with its id, and closes its database pool on shutdown.

## Install

Add the server as a platform named `api`:

```sh
kitr add server api
```

`server` is the platform type and `api` is the name you address it by (`kitr dev api`). `kitr add server` with no name stops and asks for one, because `server` is a platform type.

What `kitr add server api` does:

- Installs `@kitr/server`, `h3` and `srvx`, plus `tsx` as a dev dependency on the `node` runtime or `wrangler` on `workers`.
- Adds `@kitr/server` to `packages` in `kitrrc.ts` and writes `api: server()` into `platforms`, with the `server` import.
- Runs the [Logger](/packages/logger) recipe first if it is missing: installs `@kitr/logger`, registers its provider and writes `config/logger.ts`.
- Writes `config/server.ts` (shown under Configure) and adds it to `config/index.ts`.
- Adds `LOG_LEVEL=info` under a `# Server` comment to `.env.example`, and to `.env` when that file exists.
- Adds `dev`, `build` and `start` scripts to `package.json` (`kitr dev`, `kitr build`, `kitr start`) when they are missing.
- Writes `server/main.ts`, the server entry (shown in the first example).
- With API routes installed, writes `server/routes.ts` if it is missing and mounts it in `server/main.ts`.
- In a React project with a web platform, writes `app/routes/api.$.ts`, which sends every `/api/*` request to the same server inside TanStack Start.
- On the `workers` runtime, writes `platforms/api/wrangler.toml`.
- Adds a `kitr: server` section and a `kitr: platform api` section to `AGENTS.md`.

Platform options are flags on the same command:

```sh
kitr add server api --runtime bun --port 4000
```

| Flag | Default | Effect |
| --- | --- | --- |
| `--runtime` | `node` | `node`, `bun`, `deno` or `workers`. |
| `--port` | `3001` | Port for `kitr dev api` and `kitr start api`. |
| `--host` | | Interface to bind. |
| `--entry` | `server/main.ts` | The entry file the platform runs. |
| `--no-scaffold` | | Register the platform without writing files. |

The `fullstack`, `server`, `saas`, `site` and `realtime` kits already include a server platform named `api`. `kitr platforms remove api` takes the platform out of `kitrrc.ts`; `kitr remove server` reverses the package steps: it removes `@kitr/server`, `h3` and `srvx` from `package.json` and `kitrrc.ts`, deletes `config/server.ts` and drops the `AGENTS.md` section. It leaves `server/main.ts` and `app/routes/api.$.ts` in place, because you have likely edited them, and lists the files that still import `kitr/server`.

## Configure

`kitr add server api` writes this file:

```ts
// config/server.ts
import { defineConfig } from 'kitr/server'

export default defineConfig({
  healthPath: '/healthz',
  bodyLimit: 1024 * 1024,
})
```

`server/main.ts` passes every file in `config/` to `createServer({ config })`, so the `server` key reaches the server without more wiring.

| Option | Default | Description |
| --- | --- | --- |
| `port` | `3000` | Port `listen()` uses when you call it without one. The scaffolded `server/main.ts` always passes a port, so the platform's `port` wins. |
| `host` | `'0.0.0.0'` | Interface `listen()` binds when you call it without one. |
| `healthPath` | `'/healthz'` | Path of a route that answers `{ ok: true }` for load balancers. `false` removes the route. |
| `bodyLimit` | `1048576` (1 MiB) | Largest request body in bytes. Larger requests get a `413`. |
| `trustProxy` | `false` | Declared for proxies that set `X-Forwarded-*`. This release does not read it yet. |
| `requestIdHeader` | `'x-request-id'` | Header the request id is read from and echoed in. |
| `shutdownTimeout` | `10` | Seconds to wait for in-flight requests after `SIGINT` or `SIGTERM` before the process exits with code `1`. |
| `websocket` | `false` | Accept WebSocket upgrades through `crossws`. [Realtime](/packages/realtime) sets it for you. |

You can also pass server options in code, which overrides `config/server.ts`:

```ts
// server/main.ts
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'

export const server = createServer({
  providers: rc.providers,
  config,
  server: { shutdownTimeout: 30, requestIdHeader: 'x-acme-trace' },
})
```

| Variable | Used for |
| --- | --- |
| `LOG_LEVEL` | The server logger's level (`debug`, `info`, `warn`, `error`) when no logger provider is bound. `config/logger.ts` reads it too. |
| `PORT` | The port `server/main.ts` listens on. `kitr dev` and `kitr start` set it from the platform options. |
| `HOST` | The interface `server/main.ts` binds. `kitr dev` sets `localhost`, `kitr start` sets `0.0.0.0`. |
| `NODE_ENV` | `production` hides the message and data of `5xx` responses. |

### Platform options

The platform lives in `kitrrc.ts`. Its options decide how `kitr dev`, `kitr build` and `kitr start` run the entry.

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { server } from 'kitr/server'

export default defineKitrConfig({
  packages: ['@kitr/logger', '@kitr/server', '@kitr/api'],
  providers: [() => import('@kitr/logger')],
  platforms: {
    api: server({ runtime: 'node', port: 3001 }),
  },
})
```

| Option | Default | Description |
| --- | --- | --- |
| `runtime` | `'node'` | `node` (tsx in dev, `node --import tsx` in production), `bun`, `deno`, or `workers` (Cloudflare, through `wrangler`). |
| `port` | `3001` | Port for `kitr dev` and `kitr start`, passed to the entry as `PORT`. Must be between 0 and 65535. |
| `host` | | Interface to bind, passed as `HOST`. Defaults to `localhost` in dev and `0.0.0.0` in production. |
| `entry` | `'server/main.ts'` | The file the platform runs: `createServer({...})` plus routes and realtime. |

An unknown runtime fails when `kitrrc.ts` loads with `runtime must be one of node, bun, deno, workers`, and a bad port with `port must be a number between 0 and 65535`.

Change an option without opening the file, or override it for one run:

```sh
kitr config api port 4000
kitr config api runtime bun
KITR_API_PORT=4000 kitr dev api
kitr dev api --port 4000
```

The environment form is `KITR_<NAME>_<OPTION>`, with the platform name upper-cased and anything that is not a letter or digit turned into `_`.

## Start your first server

`kitr add server api` writes the entry. It creates the server from your providers and config, and listens when you run the file directly:

```ts
// server/main.ts
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'

/** The kitr server: providers from kitrrc.ts, config from config/. What `kitr dev api` runs, what the web platform's /api route delegates to, what tests call. */
export const server = createServer({ providers: rc.providers, config })

/** Fetch handler for runtimes that call it (Cloudflare Workers, Deno Deploy). */
export default server

const isMain = (import.meta as { main?: boolean }).main ?? process.argv[1]?.endsWith("main.ts")
if (isMain) {
  server.listen({
    port: Number(process.env.PORT) || 3001,
    host: process.env.HOST,
  })
}
```

Add a route on the underlying h3 app, below `createServer`:

```ts
// server/main.ts
// ...
export const server = createServer({ providers: rc.providers, config })

server.h3.get('/api/orders/latest', () => ({ id: 'ord_1042', customer: 'Ada', total: 129 }))
// ...
```

Start it:

```sh
kitr dev api
```

The log shows `listening on http://localhost:3001`. Ask for the order:

```sh
curl -i http://localhost:3001/api/orders/latest
```

```http
HTTP/1.1 200 OK
content-type: application/json;charset=UTF-8
x-request-id: 3106a213-994f-4363-b099-eb8c19dc7299

{"id":"ord_1042","customer":"Ada","total":129}
```

The returned object became JSON, and the response carries a fresh request id. For more than a couple of routes, use [API routes](/packages/api): controllers, validation and a typed client on top of this server.

## Run the server in development and production

`kitr dev api`, `kitr build api` and `kitr start api` run the entry with the platform's runtime. With no name they run every platform in `kitrrc.ts`.

| Runtime | `kitr dev api` | `kitr build api` | `kitr start api` |
| --- | --- | --- | --- |
| `node` | `tsx watch server/main.ts` | `tsc --noEmit -p tsconfig.json` | `node --import tsx server/main.ts` |
| `bun` | `bun --watch server/main.ts` | `tsc --noEmit -p tsconfig.json` | `bun server/main.ts` |
| `deno` | `deno run --watch -A server/main.ts` | `tsc --noEmit -p tsconfig.json` | `deno run -A server/main.ts` |
| `workers` | `wrangler dev --port 3001` in `platforms/api/` | `wrangler deploy --dry-run --outdir dist/api` | `wrangler dev` in `platforms/api/` |

On Node, Bun and Deno the build step typechecks; the server runs from source. `kitr start` binds `0.0.0.0` unless you set `host`, so the server is reachable from outside a container.

```sh
kitr build api
kitr start api --port 8080
```

## Choose a runtime

Every runtime runs the same `server/main.ts`. Only the platform option changes.

### Node

The default. `kitr add server api` installs `tsx` as a dev dependency to run TypeScript directly.

```ts
// kitrrc.ts
// ...
  platforms: { api: server({ runtime: 'node' }) },
```

### Bun

```sh
kitr config api runtime bun
```

Bun runs TypeScript itself, so no extra package is installed. `import.meta.main` tells the entry it is the main module.

### Deno

```sh
kitr config api runtime deno
```

The platform runs Deno with `-A` (all permissions). See [Deno's permissions guide](https://docs.deno.com/runtime/fundamentals/security/) to narrow them in production.

### Cloudflare Workers

```sh
kitr add server edge --runtime workers
```

The platform installs `wrangler` and writes `platforms/edge/wrangler.toml`:

```toml
# platforms/edge/wrangler.toml
name = "acme-edge"
main = "../../server/main.ts"
compatibility_date = "2025-01-01"
compatibility_flags = ["nodejs_compat"]
```

Workers call the default export's `fetch`, which `server/main.ts` already exports. `kitr build edge` bundles into `dist/edge`; deploy with `wrangler deploy` from `platforms/edge`. See the [Wrangler docs](https://developers.cloudflare.com/workers/wrangler/) for secrets and routes.

## Serve the API inside TanStack Start

In a React project with a web platform, `kitr add server api` also writes a catch-all route. Every `/api/*` request in the Start process goes to the same `server` object:

```ts
// app/routes/api.$.ts
import { createFileRoute } from '@tanstack/react-router'
import { server } from '#server/main'

/** Every /api/* request goes to the kitr server (server/main.ts), in the Start process. */
export const Route = createFileRoute('/api/$')({
  server: {
    handlers: {
      ANY: ({ request }) => server.fetch(request),
    },
  },
})
```

The web platform in `ssr` mode answers `/api/orders` itself, with no second process. `kitr dev api` still runs the server alone when you want it on its own port, for a mobile app or a partner integration.

## Call the server from any fetch runtime

`server.fetch` is a standard `(request: Request) => Promise<Response>` handler. Anything that speaks fetch can call it:

```ts
// server/worker.ts
import { server } from '#server/main'

export default { fetch: (request: Request) => server.fetch(request) }
```

```ts
// scripts/check-order.ts
import { server } from '#server/main'

const response = await server.fetch(new Request('http://app.acme.com/api/orders/latest'))
console.log(response.status, await response.json())
// => 200 { id: 'ord_1042', customer: 'Ada', total: 129 }
```

The first call to `fetch()` boots the providers, once. Outside tests it also runs each provider's `ready` hook, so job workers and schedulers start the same way they do under `listen()`.

## Add routes and middleware

`server.h3` is the [h3 app](https://h3.dev/guide/basics/routing). Register routes on it directly when you don't need controllers:

```ts
// server/main.ts
// ...
server.h3.get('/api/invoices/:id', (event) => {
  const id = event.context.params?.id
  return { id, status: 'paid' }
})
```

`server.use()` adds h3 middleware that runs for every request. Return nothing to continue; return a value or a `Response` to answer early:

```ts
// server/main.ts
// ...
server.use((event) => {
  event.res.headers.set('x-powered-by', 'acme')
})
```

`server.mount()` puts another h3 app, or any object with a `fetch` method, under a base path:

```ts
// server/main.ts
import { H3 } from 'h3'
// ...
const billing = new H3().get('/invoices', () => [{ id: 'INV-1042', total: 129 }])

server.mount('/billing', billing)
server.mount('/legacy', { fetch: (request) => fetch(`https://legacy.acme.com${new URL(request.url).pathname}`) })
```

`GET /billing/invoices` now answers from the billing app. `mount`, `use` and `mountRoutes` from [API routes](/packages/api) all return the server, so you can chain them.

## Read the current request anywhere

Every request runs inside a context you can read from any function on the server, without passing it down. `useRequest()` returns it:

```ts
// server/services/payments.ts
import { useRequest } from 'kitr/server'

export async function chargeOrder(orderId: string, amount: number) {
  const { logger, requestId } = useRequest()
  logger.info('charging order', { orderId, amount })
  return { orderId, amount, idempotencyKey: requestId }
}
```

| Field | What it holds |
| --- | --- |
| `event` | The h3 event for this request. |
| `app` | A fork of the server app: same providers and config, its own container instances. |
| `requestId` | The id from the `x-request-id` header, or a new UUID. |
| `logger` | A child logger that adds `requestId` to every line. |
| `startedAt` | `performance.now()` when the request arrived. |
| `locals` | A free-form object for middleware. [Auth](/packages/auth) puts `user` here. |

`useRequest()` outside a request throws `[kitr/server] useRequest() called outside a request.` In code that runs both inside and outside requests, such as a job or a script, use `tryUseRequest()`, which returns `undefined` instead:

```ts
// server/services/audit.ts
import { tryUseRequest } from 'kitr/server'

export function auditLabel() {
  return tryUseRequest()?.requestId ?? 'background'
}
```

## Use request-scoped services

Each request gets its own fork of the app container. A service bound per request, such as a database transaction or a cache of the current user, never leaks into another request. Read it with `useRequestApp()`:

```ts
// server/services/orders.ts
import { useRequestApp } from 'kitr/server'

export async function findOrder(id: string) {
  const db = useRequestApp().container.use('db')
  return db.orders.find(id)
}
```

Outside a request `useRequestApp()` throws `[kitr/server] useRequestApp() called outside a request and no fallback given.` Pass the server's app as a fallback for code that also runs in jobs:

```ts
// server/services/orders.ts
import { useRequestApp } from 'kitr/server'
import { server } from '#server/main'

export function ordersDb() {
  return useRequestApp(server.app).container.use('db')
}
```

Don't import services from module scope into request handlers when they hold per-user state; take them from `useRequestApp()` so each request sees its own.

## Log with the request id

The server's logger comes from the [Logger](/packages/logger) provider when it is registered, and from a built-in logger named `kitr` otherwise. Each request gets a child logger that adds `requestId`:

```ts
// server/main.ts
// ...
server.h3.post('/api/orders', async (event) => {
  const { logger } = useRequest()
  const order = await event.req.json()
  logger.info('order received', { customer: order.customer })
  return { id: 'ord_1043', ...order }
})
```

The server logs three kinds of lines for you:

- `listening on http://localhost:3001` at `info` when `listen()` starts.
- One line per request at `debug`: `POST /api/orders` with `status`, `ip` and `durationMs`.
- Every `5xx` at `error`, with the error, `method`, `path`, `status` and the request id. `4xx` responses are not logged as errors.

Set `LOG_LEVEL=debug` in `.env` to see the request lines in development.

## Trace a request across services

The server reads the request id from the `x-request-id` header when the caller sends one, and makes a UUID otherwise. It echoes the id back on the response, so a support ticket that quotes it leads to the matching log lines.

```sh
curl -i -H 'x-request-id: ticket-8812' http://localhost:3001/api/orders/latest
```

```http
HTTP/1.1 200 OK
x-request-id: ticket-8812
```

Pass the id on when you call another Acme service, so both logs share it:

```ts
// server/services/invoices.ts
import { useRequest } from 'kitr/server'

export async function fetchInvoice(id: string) {
  const { requestId } = useRequest()
  const response = await fetch(`https://billing.acme.com/invoices/${id}`, {
    headers: { 'x-request-id': requestId },
  })
  return response.json()
}
```

Set `requestIdHeader` when your proxy or tracing system uses another header name.

## Return errors as JSON

Anything thrown in a handler becomes JSON in kitr's error shape with the matching status. Throw a [`KitrError`](/packages/server/api) to choose the code:

```ts
// server/main.ts
import { KitrError } from 'kitr/app'
// ...
server.h3.post('/api/invoices/:id/pay', () => {
  throw new KitrError('CONFLICT', 'Invoice INV-1042 is already paid')
})
```

```http
HTTP/1.1 409 Conflict
content-type: application/json; charset=utf-8

{"code":"CONFLICT","message":"Invoice INV-1042 is already paid","status":409}
```

The helpers `KitrError.notFound('Order')`, `.unauthorized()`, `.forbidden()` and `.validation({ email: ['Required'] })` cover the common cases. A route that doesn't exist answers in the same shape:

```json
{ "code": "NOT_FOUND", "message": "Cannot find any route matching [GET] http://localhost:3001/api/nope", "status": 404 }
```

A plain `Error` becomes `INTERNAL` with status `500`. In development its message comes through so you can debug it. In production it does not:

```json
{ "code": "INTERNAL", "message": "Internal server error", "status": 500 }
```

> **Warning**
> Only `NODE_ENV=production` hides `5xx` messages and `data`. A staging server without it sends internal error messages, such as database errors, to the client.

`4xx` errors keep their message in every mode, so write those messages for the user.

To build the same response yourself, in custom middleware or a mounted handler, use `errorToResponse()`:

```ts
// server/main.ts
import { KitrError } from 'kitr/app'
import { errorToResponse } from 'kitr/server'
// ...
server.use((event) => {
  if (event.url.pathname.startsWith('/api/admin') && !event.req.headers.get('authorization'))
    return errorToResponse(KitrError.unauthorized(), event)
})
```

`normaliseServerError()` turns anything (an h3 `HTTPError`, a `KitrError` wrapped as a cause, a plain error) into a `KitrError` without building a response.

## Limit request bodies

`bodyLimit` caps request bodies in bytes. A request that declares a larger `content-length` is rejected before it is read, and the connection is closed so the upload stops:

```ts
// config/server.ts
import { defineConfig } from 'kitr/server'

export default defineConfig({
  healthPath: '/healthz',
  bodyLimit: 10 * 1024 * 1024, // 10 MiB for invoice PDFs
})
```

```json
{ "code": "PAYLOAD_TOO_LARGE", "message": "Request body is larger than 10485760 bytes", "status": 413 }
```

Chunked uploads without a `content-length` are counted as they stream and get a `413` with the message `Request body size exceeds the limit of 10485760 bytes`. For large files, use [Uploads](/packages/uploads), which streams to storage with its own limits.

## Check health from a load balancer

The server answers `GET /healthz` with `{ "ok": true }` and status `200` as soon as it is up. Point your load balancer or container health check at it. Move it or turn it off in `config/server.ts`:

```ts
// config/server.ts
import { defineConfig } from 'kitr/server'

export default defineConfig({
  healthPath: '/up', // or false to remove it
  bodyLimit: 1024 * 1024,
})
```

The route only says the process is serving. For a deeper check, such as the database being reachable, add your own route.

## Run code on start and shutdown

The server runs the provider lifecycle from `kitrrc.ts`. `register` and `boot` run before the first request, `ready` once the server serves, and `shutdown` when it stops. Put the work in a provider, not in `server/main.ts`:

```ts
// app/providers/orders_db_provider.ts
import { defineProvider } from 'kitr/app'
import { createPool } from '#server/db/pool'

export default defineProvider({
  name: 'orders-db',
  register(app) {
    app.container.singleton('ordersDb', () => createPool(process.env.DATABASE_URL))
  },
  ready(app) {
    app.container.use('logger').info('orders database ready')
  },
  async shutdown(app) {
    await app.container.use('ordersDb').end()
  },
})
```

```ts
// kitrrc.ts
// ...
  providers: [() => import('@kitr/logger'), () => import('#app/providers/orders_db_provider')],
```

`kitr make:provider orders_db` writes the provider skeleton. Each step happens once:

| Call | Runs |
| --- | --- |
| `server.boot()` | `register` and `boot` of every provider. `listen()` and the first `fetch()` call it for you. |
| `server.listen()` | `boot()`, then starts listening, then `ready`. |
| `server.fetch()` | `boot()`, then `ready` once, except when the app environment is `test`. |
| `server.close()` | `shutdown` of every provider. |

## Shut down without dropping requests

On `SIGINT` or `SIGTERM`, a server started with `listen()`:

1. Logs `SIGTERM received, shutting down`.
2. Stops accepting connections and ends open WebSocket connections.
3. Waits for in-flight requests to finish.
4. Runs every provider's `shutdown` (closing database pools, flushing logs).
5. Exits with code `0`.

If that takes longer than `shutdownTimeout` seconds, the process exits with code `1`. Give it more time when requests run long, such as invoice exports:

```ts
// config/server.ts
import { defineConfig } from 'kitr/server'

export default defineConfig({
  healthPath: '/healthz',
  bodyLimit: 1024 * 1024,
  shutdownTimeout: 30,
})
```

Keep the timeout below your orchestrator's grace period (30 seconds by default on Kubernetes), or the process is killed before it finishes.

`listen()` returns a `close()` function that does steps 2 to 4 without exiting, which is what tests and scripts use:

```ts
// scripts/smoke.ts
import { server } from '#server/main'

const { url, close } = await server.listen({ port: 0, host: '127.0.0.1' })
const response = await fetch(`${url}/healthz`)
console.log(await response.json())
// => { ok: true }
await close()
```

Port `0` picks a free port; `url` tells you which one.

## Accept WebSocket connections

Set `websocket: true` to accept WebSocket upgrades through [crossws](https://crossws.h3.dev). [Realtime](/packages/realtime) sets this for you and attaches its channels with `realtime.attach(server, '/ws')` in `server/main.ts`.

```ts
// server/main.ts
// ...
export const server = createServer({ providers: rc.providers, config, server: { websocket: true } })
```

Without the `crossws` package installed, `listen()` throws `[kitr/server] websocket: true needs the crossws package.` Run `kitr add realtime`, which installs it.

## Commands

`kitr/server` adds no generators of its own. The server platform answers these commands:

| Command | What it does |
| --- | --- |
| `kitr add server <name>` | Adds a server platform: installs the packages, writes `platforms.<name>` in `kitrrc.ts`, runs the server and logger recipes, adds scripts and scaffolds `server/main.ts`. |
| `kitr dev <name>` | Runs the entry in watch mode for the runtime (see the table under "Run the server in development and production"). |
| `kitr build <name>` | Typechecks on Node, Bun and Deno; bundles into `dist/<name>` on Workers. |
| `kitr start <name>` | Runs the production server. `kitr serve` does the same. |
| `kitr config <name> [option] [value]` | Reads or sets a platform option in `kitrrc.ts`. `--unset` removes one. |
| `kitr platforms` | Lists platforms and their options. |
| `kitr platforms scaffold <name>` | Rewrites the platform's files (`server/main.ts`, `app/routes/api.$.ts`, `wrangler.toml`). |
| `kitr platforms remove <name>` | Takes the platform out of `kitrrc.ts`. |

`kitr add server api` prints `api: kitr dev api · kitr build api · kitr config api` when it finishes.

`kitr doctor` reports an error when:

- The entry file (`server/main.ts`) is missing. Fix: `kitr platforms scaffold api`.
- `h3` or `srvx` is not installed.
- `tsx` is not installed on the `node` runtime.
- `wrangler` is not installed on the `workers` runtime.
- The project has a server platform but no `server/main.ts`.

## Errors

| Code | When | What to do |
| --- | --- | --- |
| `NOT_FOUND` (404) | No route matches the method and path. | Check the path and method; with API routes, run `kitr routes:list`. |
| `PAYLOAD_TOO_LARGE` (413) | The body is larger than `bodyLimit`. | Raise `bodyLimit` or send large files through [Uploads](/packages/uploads). |
| `INTERNAL` (500) | A handler threw something that is not a `KitrError`. | Read the `error` log line with the request id; throw a `KitrError` for expected failures. |
| any `KitrError` code | A handler threw a `KitrError`. | The status follows the code: `VALIDATION` 422, `UNAUTHORIZED` 401, `FORBIDDEN` 403, `CONFLICT` 409, `RATE_LIMITED` 429. |

These are thrown as plain errors, not JSON responses:

| Message | When | What to do |
| --- | --- | --- |
| `[kitr/server] useRequest() called outside a request.` | `useRequest()` ran in a job, script or module scope. | Use `tryUseRequest()`, or move the call into the handler. |
| `[kitr/server] useRequestApp() called outside a request and no fallback given.` | Same, for `useRequestApp()`. | Pass a fallback: `useRequestApp(server.app)`. |
| `[kitr/server] websocket: true needs the crossws package.` | `websocket: true` without `crossws`. | `kitr add realtime`. |

## Testing

Tests call `server.fetch()` with a `Request`. No port is opened. Import the server from `server/main.ts` and use `createTestClient` from [Testing](/packages/testing) for short calls:

```ts
// test/orders.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

it('returns the latest order', async () => {
  const client = createTestClient(server)
  const res = await client.get<{ id: string; customer: string }>('/api/orders/latest')
  expect(res.status).toBe(200)
  expect(res.body).toEqual({ id: 'ord_1042', customer: 'Ada', total: 129 })
  expect(res.headers.get('x-request-id')).toBeTruthy()
})
```

To test server behaviour in isolation, build a server in the test. Pass `silentLogger` to keep the output clean and `server` options to change config:

```ts
// test/server.test.ts
import { KitrError } from 'kitr/app'
import { silentLogger } from 'kitr/logger'
import { createServer, useRequest } from 'kitr/server'
import { createTestClient } from 'kitr/testing'
import { describe, expect, it } from 'vitest'

function buildServer() {
  const server = createServer({ logger: silentLogger, server: { bodyLimit: 1024 } })
  server.h3.get('/api/orders/:id', (event) => {
    const id = event.context.params?.id
    if (id !== 'ord_1042') throw KitrError.notFound('Order')
    return { id, requestId: useRequest().requestId }
  })
  server.h3.post('/api/orders', async (event) => ({ received: (await event.req.text()).length }))
  return server
}

describe('order service', () => {
  it('answers with the order and echoes the request id', async () => {
    const client = createTestClient(buildServer(), { headers: { 'x-request-id': 'ticket-8812' } })
    const res = await client.get<{ id: string; requestId: string }>('/api/orders/ord_1042')
    expect(res.status).toBe(200)
    expect(res.body).toEqual({ id: 'ord_1042', requestId: 'ticket-8812' })
    expect(res.headers.get('x-request-id')).toBe('ticket-8812')
  })

  it('returns a kitr error for a missing order', async () => {
    const res = await createTestClient(buildServer()).get('/api/orders/ord_9999')
    expect(res.status).toBe(404)
    expect(res.body).toEqual({ code: 'NOT_FOUND', message: 'Order not found', status: 404 })
  })

  it('rejects bodies over the limit', async () => {
    const res = await createTestClient(buildServer()).post('/api/orders', { note: 'x'.repeat(2048) })
    expect(res.status).toBe(413)
    expect(res.body).toMatchObject({ code: 'PAYLOAD_TOO_LARGE' })
  })

  it('answers the health check', async () => {
    const res = await createTestClient(buildServer()).get('/healthz')
    expect(res.body).toEqual({ ok: true })
  })
})
```

Under Vitest the app environment is `test`, so `fetch()` boots providers but does not run their `ready` hooks: job workers and schedulers stay off. To test lifecycle hooks, call `server.listen({ port: 0 })` and `close()` as shown under "Shut down without dropping requests".

## Next steps

- [API reference](/packages/server/api)
- [API routes](/packages/api): routes, controllers, validation and a typed client on this server
- [Logger](/packages/logger): levels, formats and the request-scoped logger
- [Realtime](/packages/realtime): WebSocket channels attached to this server
- [A backend without React](/docs/pure-backend)
- [h3 documentation](https://h3.dev)


# Shield API

Source: https://kitr.dev/packages/shield/api

Every export of `kitr/shield`, `kitr/shield/provider`, read from the published type definitions. The [guide](/packages/shield) shows them in use.

## kitr/shield

### cors

```ts
function cors(options?: CorsOptions): Middleware;
```

Middleware that answers CORS preflights with 204 and adds `Access-Control-Allow-*` headers for allowed origins. Throws at once for `origin: '*'` with credentials.

### createMemoryRateLimitStore

```ts
function createMemoryRateLimitStore(): RateLimitStore;
```

The default rate-limit store: counters in this process, pruned past 10,000 keys. Each instance counts on its own.

### csrf

```ts
function csrf(options?: CsrfOptions): Middleware;
```

Double-submit cookie CSRF: a readable cookie carries a token the browser must echo in a header
(`fetch` from another origin cannot read the cookie, so it cannot forge the header). kitr/http
sends the header automatically.

### rateLimit

```ts
function rateLimit(options?: RateLimitOptions): Middleware;
```

Fixed-window rate limit with `RateLimit-*` headers and a 429 when exceeded.

### securityHeaders

```ts
function securityHeaders(options?: HeadersOptions): Middleware;
```

Middleware that sets nosniff, frame, referrer, permissions, CSP and (in production) HSTS headers on every response, errors included.

### shield

```ts
function shield<S extends {
  use(middleware: Middleware): unknown;
  app?: {
    config: any;
  };
}>(server: S, config?: ShieldConfig): S;
```

Attach the shield to a kitr server (or any object with `use(middleware)`), reading `config/shield.ts`.

### shieldMiddlewares

```ts
function shieldMiddlewares(config?: ShieldConfig): Middleware[];
```

The middlewares `config/shield.ts` asks for, in the right order.

### DEFAULT_CSP

```ts
const DEFAULT_CSP = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' ws: wss:; frame-ancestors 'none'; base-uri 'self'; form-action 'self'";
```

The Content-Security-Policy `securityHeaders()` sends when you don't set one: same-origin everything, inline scripts and styles allowed, no framing.

### defineConfig

```ts
const defineConfig: <const C extends ShieldConfig>(config: C) => C;
```

Type the default export of `config/shield.ts`. Returns its argument unchanged.

### CorsOptions

```ts
interface CorsOptions {
  /** `'*'`, a list of origins, or a predicate. Default: same-origin only (no header). */
  origin?: '*' | string[] | ((origin: string) => boolean);
  /** Methods a preflight allows. Default GET, POST, PUT, PATCH, DELETE, OPTIONS. */
  methods?: string[];
  /** Request headers a preflight allows. Default Content-Type, Authorization, X-CSRF-Token, X-Requested-With. */
  headers?: string[];
  /** Let the browser send cookies cross-origin. Refused together with `origin: '*'`. Default false. */
  credentials?: boolean;
  /** Seconds a preflight answer may be cached. Default 600. */
  maxAge?: number;
}
```

Options for `cors()` and the `cors` key of `config/shield.ts`.

### CsrfOptions

```ts
interface CsrfOptions {
  /** Cookie that carries the token. Default `kitr-csrf`. */
  cookie?: string;
  /** Header the client sends it back in. Default `x-csrf-token`. */
  header?: string;
  /** Methods that need a token. Default POST, PUT, PATCH and DELETE. */
  methods?: string[];
  /** Paths that never need a token (webhooks). Prefix match. */
  ignore?: string[];
  /** Add `Secure` to the cookie. Default: true when `NODE_ENV` is `production`. */
  secure?: boolean;
}
```

Options for `csrf()` and the `csrf` key of `config/shield.ts`.

### HeadersOptions

```ts
interface HeadersOptions {
  /** `Content-Security-Policy`. A string, or false to leave it out. Default: a strict policy for an SPA/SSR app. */
  contentSecurityPolicy?: string | false;
  /** `Strict-Transport-Security` max-age in seconds; false to leave it out. Default one year in production. */
  hsts?: number | false;
  /** `X-Frame-Options`. Default `DENY`; false to leave it out. */
  frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
  /** `Referrer-Policy`. Default `strict-origin-when-cross-origin`; false to leave it out. */
  referrerPolicy?: string | false;
  /** `Permissions-Policy`. Default `camera=(), microphone=(), geolocation=()`; false to leave it out. */
  permissionsPolicy?: string | false;
}
```

Options for `securityHeaders()` and the `headers` key of `config/shield.ts`.

### RateLimitOptions

```ts
interface RateLimitOptions {
  /** Window length in milliseconds. Default 60 000. */
  windowMs?: number;
  /** Requests per key per window. Default 100. */
  max?: number;
  /** Key a request. Default: the client IP. */
  key?: (event: H3Event) => string;
  /**
   * Read the client IP from `X-Forwarded-For` (first entry). Only turn this on behind a proxy
   * you control that overwrites the header: otherwise any client can send a new value with every
   * request and is never limited. Default false: the address of the connection.
   */
  trustProxy?: boolean;
  /** Where counters live. Default: this process. */
  store?: RateLimitStore;
  /** Paths that are never limited. Prefix match. */
  ignore?: string[];
}
```

Options for `rateLimit()` and the `rateLimit` key of `config/shield.ts`.

### RateLimitStore

```ts
interface RateLimitStore {
  /** Increment and return the count and when the window resets (ms epoch). */
  hit(key: string, windowMs: number): Promise<{
    count: number;
    resetAt: number;
  }>;
}
```

Where rate-limit counters live. Implement it over Redis to share limits between instances.

### ShieldConfig

```ts
interface ShieldConfig {
  /** Security headers. On unless false. */
  headers?: HeadersOptions | false;
  /** CORS. Off unless set to an object. */
  cors?: CorsOptions | false;
  /** Double-submit cookie CSRF. On unless false. */
  csrf?: CsrfOptions | false;
  /** Fixed-window rate limit. On unless false. */
  rateLimit?: RateLimitOptions | false;
}
```

The options in `config/shield.ts`. Each key takes its middleware's options, or false to turn it off.

## kitr/shield/provider

### shieldProvider

```ts
const shieldProvider: import("@kitr/core").KitrProvider;
```

Validates `config/shield.ts` at boot (refuses `origin: '*'` with credentials); `shield(server)` in server/main.ts attaches the middleware.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Shield

Source: https://kitr.dev/packages/shield

Every API that a browser can reach gets the same unwanted visitors: other sites that try to post forms as your signed-in users, pages that frame yours to trick clicks, scripts that hammer the sign-in route. `kitr/shield` turns on the four defences every API needs, from one config file: safe response headers, CORS for a separate front end, CSRF protection for cookie sessions, and a rate limit per client.

Each defence is a plain [h3](https://h3.dev/guide/basics/middleware) middleware with no dependencies of its own. kitr adds the defaults, the order they run in, a config file, and refusals for settings that would open a hole, such as CORS for every origin with cookies.

It runs on the server only, in front of every route of the [kitr server](/packages/server). It does not know who the user is: sign-in, sessions and permissions are [auth](/packages/auth)'s job.

The examples on this page follow Acme's API at `api.acme.com`, used by the dashboard at `app.acme.com`. People sign in with a cookie session, and Stripe posts payment webhooks to `/webhooks/stripe`.

## Install

```sh
kitr add shield
```

What `kitr add` does:

- Adds the [server](/packages/server) package first if the project does not have it yet (and [logger](/packages/logger), which the server needs).
- Adds `@kitr/shield` to `dependencies` in `package.json` and installs it. Pass `--no-install` to skip the install.
- Adds `() => import('@kitr/shield/provider')` to `providers` and `'@kitr/shield'` to `packages` in `kitrrc.ts`. The provider checks `config/shield.ts` at boot.
- Writes `config/shield.ts` (see [Configure](#configure)).
- Edits `server/main.ts`, when it exists and does not already call `shield(server`: imports `shield` from `kitr/shield` and calls `shield(server)` straight after `createServer()`, so the shield sees every request first.
- Adds a `## kitr: shield` section to `AGENTS.md`: `shield(server)` applies `config/shield.ts`, rate-limited requests get 429 with `RateLimit-*` headers, CSRF failures get 403, and agents tune the config instead of adding helmet or cors by hand.

It adds no env variables, no scripts and asks no questions. No kit includes the shield, so every project adds it with this command.

After `kitr add shield`, the top of `server/main.ts` reads:

```ts
// server/main.ts
import { createServer } from 'kitr/server'
import { shield } from 'kitr/shield'
import { mountRoutes } from 'kitr/api'
import { config } from '../config'
import rc from '../kitrrc'
import { routes } from './routes'

export const server = createServer({ providers: rc.providers, config })
// Security headers, CORS, rate limit and CSRF from config/shield.ts.
shield(server)
mountRoutes(server, routes)
// ...
```

If the project has no `server/main.ts` yet, add those two lines yourself once the server platform has written it (`kitr add server api`).

`kitr remove shield` takes the provider and the package out of `kitrrc.ts`, deletes `config/shield.ts`, removes the dependency and the `AGENTS.md` section. It leaves `server/main.ts` alone, so delete the `shield` import and the `shield(server)` line yourself.

## Configure

`kitr add shield` writes this file:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  headers: {}, // sensible security headers; set contentSecurityPolicy to tighten
  cors: false, // { origin: ['https://app.example.com'], credentials: true } for a separate front end
  rateLimit: { max: 300, windowMs: 60_000 }, // per IP per minute
  csrf: {}, // double-submit cookie; kitr/http sends the token on every non-GET request
})
```

Each key takes its middleware's options, or `false` to turn it off. Headers, rate limiting and CSRF are on when their key is missing; CORS is off unless you set it. The defaults below are the ones the middleware uses when an option is left out. The generated file sets `rateLimit.max` to 300.

| Option | Default | Description |
| --- | --- | --- |
| `headers` | `{}` (on) | Security headers on every response. `false` turns them all off. |
| `headers.contentSecurityPolicy` | `DEFAULT_CSP` | `Content-Security-Policy` value, or `false` to leave it out. |
| `headers.hsts` | one year in production, `false` otherwise | `Strict-Transport-Security` max-age in seconds, or `false`. Always adds `includeSubDomains`. |
| `headers.frameOptions` | `'DENY'` | `X-Frame-Options`: `'DENY'`, `'SAMEORIGIN'` or `false`. |
| `headers.referrerPolicy` | `'strict-origin-when-cross-origin'` | `Referrer-Policy`, or `false`. |
| `headers.permissionsPolicy` | `'camera=(), microphone=(), geolocation=()'` | `Permissions-Policy`, or `false`. |
| `cors` | `false` (off) | CORS for a front end on another origin. |
| `cors.origin` | none: no CORS headers | `'*'`, a list of exact origins, or `(origin) => boolean`. |
| `cors.methods` | `GET, POST, PUT, PATCH, DELETE, OPTIONS` | Methods a preflight allows. |
| `cors.headers` | `Content-Type, Authorization, X-CSRF-Token, X-Requested-With` | Request headers a preflight allows. |
| `cors.credentials` | `false` | Let the browser send cookies. Refused with `origin: '*'`. |
| `cors.maxAge` | `600` | Seconds a browser may cache a preflight answer. |
| `rateLimit` | `{}` (on) | Fixed-window limit per client. `false` turns it off. |
| `rateLimit.windowMs` | `60000` | Window length in milliseconds. |
| `rateLimit.max` | `100` | Requests per key per window. |
| `rateLimit.key` | client IP | `(event) => string`: what counts as one client. |
| `rateLimit.trustProxy` | `false` | Read the client IP from the first `X-Forwarded-For` entry. |
| `rateLimit.store` | memory | Where counters live. Any `RateLimitStore`. |
| `rateLimit.ignore` | none | Path prefixes that are never limited. |
| `csrf` | `{}` (on) | Double-submit cookie CSRF. `false` turns it off. |
| `csrf.cookie` | `'kitr-csrf'` | Cookie that carries the token. |
| `csrf.header` | `'x-csrf-token'` | Header the client echoes the token in. |
| `csrf.methods` | `POST, PUT, PATCH, DELETE` | Methods that need a token. |
| `csrf.ignore` | none | Path prefixes that never need a token. |
| `csrf.secure` | `true` in production | Add `Secure` to the cookie. |

The shield reads one env variable:

| Variable | Used for |
| --- | --- |
| `NODE_ENV` | `production` turns on HSTS and the `Secure` flag on the CSRF cookie. |

Config files are TypeScript, so you can vary values per environment. Tests often turn the rate limit off, because every test request comes from the same client:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  headers: {},
  cors: { origin: ['https://app.acme.com'], credentials: true },
  rateLimit: process.env.NODE_ENV === 'test' ? false : { max: 300, windowMs: 60_000 },
  csrf: { ignore: ['/webhooks'] },
})
```

## Protect your API

After `kitr add shield`, start the server and ask it for anything:

```sh
curl -i http://localhost:3001/api/health
```

The response now carries the shield's headers:

```http
HTTP/1.1 200 OK
content-security-policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' ws: wss:; frame-ancestors 'none'; base-uri 'self'; form-action 'self'
permissions-policy: camera=(), microphone=(), geolocation=()
ratelimit-limit: 300
ratelimit-remaining: 299
ratelimit-reset: 60
referrer-policy: strict-origin-when-cross-origin
set-cookie: kitr-csrf=ed33bfe66a21a75f218cbf44dd6d230f0f9087dbed1c8fc0; Path=/; SameSite=Lax
x-content-type-options: nosniff
x-frame-options: DENY
```

A `POST` without the CSRF token is refused:

```sh
curl -i -X POST http://localhost:3001/api/projects
```

```http
HTTP/1.1 403 Forbidden
content-type: application/json; charset=utf-8

{"code":"FORBIDDEN","message":"CSRF token missing or invalid","status":403}
```

Your own front end doesn't see that error: [kitr/http](/packages/http) reads the `kitr-csrf` cookie and sends it back as `x-csrf-token` on every request that is not `GET`, `HEAD` or `OPTIONS`.

## Set security headers

`securityHeaders()` sets six headers on every response, error pages included:

| Header | Default value | Stops |
| --- | --- | --- |
| `X-Content-Type-Options` | `nosniff` | Browsers guessing a file is script. Always on. |
| `X-Frame-Options` | `DENY` | Other sites framing your pages (clickjacking). |
| `Referrer-Policy` | `strict-origin-when-cross-origin` | Full URLs leaking to other sites. |
| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` | Pages using devices they don't need. |
| `Content-Security-Policy` | `DEFAULT_CSP` | Scripts, styles and frames from other origins. |
| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` in production | Plain-HTTP visits after the first HTTPS one. |

Change one header and the rest keep their defaults. Acme's dashboard needs its own page to frame the invoice preview, and the help widget needs the microphone:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  headers: {
    frameOptions: 'SAMEORIGIN',
    permissionsPolicy: 'camera=(), microphone=(self), geolocation=()',
  },
})
```

Set a header to `false` to leave it out, for example when a proxy in front of the server already sends it. `X-Content-Type-Options: nosniff` can't be turned off.

## Tighten the Content-Security-Policy

`DEFAULT_CSP` allows scripts, styles, fonts and images from your own origin only, plus inline scripts and styles, which server-rendered React needs. Connections may go to your origin and to any WebSocket. Nothing may frame the page. The full value:

```ts
// server/security/csp.ts
import { DEFAULT_CSP } from 'kitr/shield'

console.log(DEFAULT_CSP)
// => default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';
//    img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' ws: wss:;
//    frame-ancestors 'none'; base-uri 'self'; form-action 'self'
```

When a page loads something from another origin, write the whole policy. Acme loads Stripe.js, avatars from `cdn.acme.com` and calls the API from the dashboard:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

const csp = [
  "default-src 'self'",
  "script-src 'self' 'unsafe-inline' https://js.stripe.com",
  "style-src 'self' 'unsafe-inline'",
  "img-src 'self' data: blob: https://cdn.acme.com",
  "font-src 'self' data:",
  "connect-src 'self' https://api.acme.com wss://api.acme.com",
  'frame-src https://js.stripe.com',
  "frame-ancestors 'none'",
  "base-uri 'self'",
  "form-action 'self'",
].join('; ')

export default defineConfig({
  headers: { contentSecurityPolicy: csp },
})
```

A resource the policy blocks shows up as an error in the browser console, naming the directive that refused it. See [MDN's CSP reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) for every directive.

Don't fix a blocked resource with `default-src *`. Add the one origin that needs it to the one directive that names it.

## Turn on HSTS in production

HSTS tells browsers to use HTTPS for your domain, and its subdomains, for the next `max-age` seconds. The shield sends it only when `NODE_ENV` is `production`, with a max-age of one year. To roll it out carefully, start short and raise it once every subdomain serves HTTPS:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  headers: { hsts: process.env.NODE_ENV === 'production' ? 300 : false },
})
```

> **Warning**
> HSTS includes `includeSubDomains`. Once a browser has seen it, every subdomain of `acme.com` must serve HTTPS until the max-age runs out. A subdomain that only speaks HTTP becomes unreachable for those visitors.

## Allow a separate front end

Browsers refuse to let a page on one origin read responses from another unless the API says so with CORS. When the dashboard at `app.acme.com` calls the API at `api.acme.com`, list the dashboard's origin:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  cors: { origin: ['https://app.acme.com'], credentials: true },
})
```

A request from `https://app.acme.com` now gets `Access-Control-Allow-Origin: https://app.acme.com`, `Access-Control-Allow-Credentials: true` and `Vary: Origin`. A preflight (`OPTIONS`) from it gets `204 No Content` with the allowed methods, headers and max-age, before any route, rate limit or CSRF check runs. A request from any other origin gets no CORS headers, so the browser blocks the read.

Origins in the list match exactly. `https://app.acme.com.evil.com`, `http://app.acme.com` and `https://app.acme.co` are all refused. To allow preview deploys on subdomains, pass a function:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  cors: {
    origin: (origin) => origin === 'https://app.acme.com' || /^https:\/\/[a-z0-9-]+\.preview\.acme\.com$/.test(origin),
    credentials: true,
  },
})
```

Don't write `origin.endsWith('acme.com')`: `https://evilacme.com` ends with it too. Anchor the pattern and include the dot.

For a public, read-only API with no cookies, `origin: '*'` answers `Access-Control-Allow-Origin: *` to everyone. Combining `'*'` with `credentials: true` would let any website send requests with your users' cookies, so the shield refuses it. `cors()` throws when it is created, and the provider stops the app at boot:

```text
Error: [kitr/shield] cors.origin "*" cannot be combined with credentials; list the origins instead.
```

Projects scaffolded from a kit put `cors()` from [kitr/api](/packages/api) on the `/api` route group. Once the shield handles CORS, remove that middleware from `server/routes.ts`, so one place decides which origins may call the API.

## Protect cookie sessions from CSRF

CSRF is another site making the browser post to your API with your user's cookies attached. The shield uses the double-submit cookie pattern: it sets a random token in a readable `kitr-csrf` cookie, and every `POST`, `PUT`, `PATCH` and `DELETE` must send the same value back in the `x-csrf-token` header. Another site can make the browser send the cookie, but it cannot read it, so it cannot write the header.

The cookie is set on the first response that finds none: 48 hex characters, `Path=/`, `SameSite=Lax`, plus `Secure` in production. It is not `HttpOnly`, because your own page has to read it.

With [kitr/http](/packages/http), you do nothing. With plain `fetch`, read the cookie and send it:

```ts
// app/lib/post_json.ts
function csrfToken(): string | undefined {
  const match = document.cookie.match(/(?:^|;\s*)kitr-csrf=([^;]+)/)
  return match ? decodeURIComponent(match[1]!) : undefined
}

export async function postJson(path: string, body: unknown) {
  const response = await fetch(path, {
    method: 'POST',
    credentials: 'include',
    headers: { 'content-type': 'application/json', 'x-csrf-token': csrfToken() ?? '' },
    body: JSON.stringify(body),
  })
  return response.json()
}

// await postJson('/api/projects', { name: 'Billing v2' })
// => { id: '7', name: 'Billing v2' }
```

A missing header, a header that differs from the cookie, or a header with no cookie all get `403` with code `FORBIDDEN`.

You can rename the cookie and header with `csrf.cookie` and `csrf.header`. kitr/http always reads `kitr-csrf` and sends `x-csrf-token`, so renaming either means sending the token yourself.

The cookie has no `Domain` attribute, so only pages on the API's own host can read it. When the front end lives on another host, as `app.acme.com` does for `api.acme.com`, serve the API under the front end's host (`app.acme.com/api` through a proxy, or the web platform's `/api/*` route), or authenticate that front end with a bearer token instead of a cookie.

An API that authenticates every request with an `Authorization` header and never with cookies, such as one used only by Acme's mobile app, is not exposed to CSRF. There, `csrf: false` is safe:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  csrf: false, // bearer tokens only: no cookie for another site to ride on
})
```

> **Warning**
> Turn CSRF off only when no route accepts a cookie session. One cookie-authenticated `POST` behind `csrf: false` is open to every site your users visit.

## Accept webhooks

Stripe, GitHub and other services post to your API from their servers. They have no cookie and send no CSRF header. Exempt their paths with `csrf.ignore`, and keep them out of the rate limit, which would count every webhook from one provider as one client:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  csrf: { ignore: ['/webhooks'] },
  rateLimit: { max: 300, windowMs: 60_000, ignore: ['/webhooks', '/healthz'] },
})
```

`ignore` matches path prefixes on a segment boundary: `/webhooks` covers `/webhooks` and `/webhooks/stripe`, but not `/webhooksfake`. An exempt route must check the request itself, for example by verifying Stripe's signature header, because nothing else now stands in front of it.

## Rate limit requests

The rate limit counts requests per client in fixed windows. The generated config allows 300 requests per IP per minute. Every response says where the client stands:

| Header | Value |
| --- | --- |
| `RateLimit-Limit` | `max` |
| `RateLimit-Remaining` | Requests left in this window |
| `RateLimit-Reset` | Seconds until the window resets |
| `Retry-After` | Seconds to wait; only on a 429 |

The request after the last allowed one gets `429`:

```http
HTTP/1.1 429 Too Many Requests
ratelimit-limit: 300
ratelimit-remaining: 0
ratelimit-reset: 41
retry-after: 41

{"code":"RATE_LIMITED","message":"Too many requests","status":429}
```

The window is fixed: it starts with a client's first request and resets `windowMs` later, whatever happened in between. A client can therefore send up to `2 × max` requests across a window boundary. For a global limit that is fine.

Rate limiting runs before CSRF, so a flood of forged posts is cut off by the counter before any token is compared. Preflights are answered by CORS before the rate limit, so they never count.

## Limit one route more tightly

The config sets one limit for the whole server. For a stricter limit on one route, such as sign-in, wrap `rateLimit()` in a middleware that only applies on that path and add it after the shield:

```ts
// server/security/sign_in_limit.ts
import { rateLimit } from 'kitr/shield'
import type { Middleware } from 'h3'

const limiter = rateLimit({ max: 5, windowMs: 15 * 60_000 })

/** Five sign-in attempts per IP per 15 minutes, on top of the global limit. */
export const signInLimit: Middleware = (event, next) =>
  new URL(event.req.url).pathname === '/api/auth/sign-in' ? limiter(event, next) : next()
```

```ts
// server/main.ts
import { createServer } from 'kitr/server'
import { shield } from 'kitr/shield'
import { config } from '../config'
import rc from '../kitrrc'
import { signInLimit } from './security/sign_in_limit'

export const server = createServer({ providers: rc.providers, config })
// Security headers, CORS, rate limit and CSRF from config/shield.ts.
shield(server)
server.use(signInLimit)
// ...
```

The sixth attempt from one IP within 15 minutes gets `429`. The headers on that response describe the tighter limit, because it runs last.

## Run behind a proxy

By default the rate limit keys on the address of the TCP connection. Behind a load balancer or CDN, that is the proxy's address, so every visitor shares one counter and the whole site is limited together. Turn on `trustProxy` to read the client from `X-Forwarded-For`:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  rateLimit: { max: 300, windowMs: 60_000, trustProxy: true },
})
```

The shield then uses the first entry of `X-Forwarded-For`. A request with neither a header nor a connection address is counted under `anonymous`.

> **Warning**
> Only set `trustProxy: true` when every request passes through a proxy you control that overwrites `X-Forwarded-For`. Without one, a client can send a new value with each request and is never limited.

## Key the limit on something else

`rateLimit.key` decides what counts as one client. It gets the [h3 event](https://h3.dev/guide/api/h3event) and returns a string. Acme's partner API is called from a few servers that each send an `x-acme-partner` id; limit per partner, falling back to the IP:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'

export default defineConfig({
  rateLimit: {
    max: 1000,
    windowMs: 60_000,
    key: (event) =>
      event.req.headers.get('x-acme-partner') ?? (event.req as { ip?: string }).ip ?? 'anonymous',
  },
})
```

The shield runs before your routes and before auth middleware, so the signed-in user is not known yet when `key` runs. Key on something in the request itself.

Only key on a header that a client cannot change at will, or that you verify elsewhere. A client that can invent a new key per request gets a fresh counter every time.

## Use the middlewares one by one

`shield(server)` reads `config/shield.ts` and adds the middlewares in a fixed order: headers, CORS, rate limit, CSRF. Pass a config as the second argument to skip the file:

```ts
// server/main.ts
import { createServer } from 'kitr/server'
import { shield } from 'kitr/shield'

export const server = createServer()
shield(server, { cors: { origin: ['https://app.acme.com'] }, csrf: false })
```

`shieldMiddlewares(config)` returns the same list without attaching it, for any server with a `use()` method. Each middleware is also exported on its own:

```ts
// server/main.ts
import { createServer } from 'kitr/server'
import { cors, csrf, rateLimit, securityHeaders } from 'kitr/shield'

export const server = createServer()
server.use(securityHeaders({ frameOptions: 'SAMEORIGIN' }))
server.use(cors({ origin: ['https://app.acme.com'], credentials: true }))
server.use(rateLimit({ max: 300 }))
server.use(csrf({ ignore: ['/webhooks'] }))
```

| Export | Returns | Description |
| --- | --- | --- |
| `shield(server, config?)` | the server | Attach every middleware the config asks for. |
| `shieldMiddlewares(config)` | `Middleware[]` | The same list, unattached. `{}` gives headers, rate limit and CSRF. |
| `securityHeaders(options)` | `Middleware` | Security headers. |
| `cors(options)` | `Middleware` | CORS and preflights. |
| `rateLimit(options)` | `Middleware` | Fixed-window limit. |
| `csrf(options)` | `Middleware` | Double-submit cookie CSRF. |
| `createMemoryRateLimitStore()` | `RateLimitStore` | The default in-process counter store. |

Keep the order when you attach them by hand: CORS must answer preflights before the rate limit and CSRF see them, and the rate limit must run before CSRF.

## Errors

| Code | When | What to do |
| --- | --- | --- |
| `FORBIDDEN` (403) | A `POST`, `PUT`, `PATCH` or `DELETE` without a CSRF header, or with one that differs from the `kitr-csrf` cookie. Message `CSRF token missing or invalid`. | Send the request with [kitr/http](/packages/http), or read the cookie and send `x-csrf-token`. Add webhook paths to `csrf.ignore`. |
| `RATE_LIMITED` (429) | A client sent more than `max` requests in the window. Message `Too many requests`. | Wait `Retry-After` seconds. On your side, raise `max`, add `ignore` paths, or set `trustProxy` behind a proxy. |
| Boot error | `cors.origin` is `'*'` and `cors.credentials` is `true`. | List the origins instead of `'*'`. |

Both runtime errors are `KitrError` responses, so the body is `{ code, message, status }` and kitr/http throws them as `KitrError` on the client. The 429 still carries the CORS headers, so the front end can read it and show a message.

## Testing

Build a small server in the test, attach the shield with an explicit config, and call `server.fetch()`. This needs no network and no port:

```ts
// server/security/shield.test.ts
import { silentLogger } from 'kitr/logger'
import { createServer } from 'kitr/server'
import { shield } from 'kitr/shield'
import { describe, expect, it } from 'vitest'

function acmeServer() {
  const server = createServer({ logger: silentLogger })
  shield(server, {
    cors: { origin: ['https://app.acme.com'], credentials: true },
    rateLimit: { max: 2, windowMs: 60_000, key: () => 'ada' },
    csrf: { ignore: ['/webhooks'] },
  })
  server.h3.get('/api/projects', () => [{ id: '1', name: 'Billing v2' }])
  server.h3.post('/api/projects', () => ({ id: '2' }))
  server.h3.post('/webhooks/stripe', () => ({ received: true }))
  return server
}

describe('shield', () => {
  it('sets security headers and answers the dashboard origin', async () => {
    const res = await acmeServer().fetch(
      new Request('http://api.acme.com/api/projects', { headers: { origin: 'https://app.acme.com' } }),
    )
    expect(res.status).toBe(200)
    expect(res.headers.get('x-frame-options')).toBe('DENY')
    expect(res.headers.get('access-control-allow-origin')).toBe('https://app.acme.com')
  })

  it('refuses a POST without the CSRF token and accepts one with it', async () => {
    const server = acmeServer()
    const denied = await server.fetch(new Request('http://api.acme.com/api/projects', { method: 'POST' }))
    expect(denied.status).toBe(403)
    expect(await denied.json()).toMatchObject({ code: 'FORBIDDEN' })

    const token = 'a'.repeat(48)
    const allowed = await server.fetch(
      new Request('http://api.acme.com/api/projects', {
        method: 'POST',
        headers: { cookie: `kitr-csrf=${token}`, 'x-csrf-token': token },
      }),
    )
    expect(allowed.status).toBe(200)
  })

  it('lets webhooks through without a token and limits the third request', async () => {
    const server = acmeServer()
    const hook = await server.fetch(new Request('http://api.acme.com/webhooks/stripe', { method: 'POST' }))
    expect(hook.status).toBe(200)
    const second = await server.fetch(new Request('http://api.acme.com/api/projects'))
    expect(second.headers.get('ratelimit-remaining')).toBe('0')
    const limited = await server.fetch(new Request('http://api.acme.com/api/projects'))
    expect(limited.status).toBe(429)
    expect(limited.headers.get('retry-after')).toBeTruthy()
  })
})
```

`webhooks/stripe` is exempt from CSRF but still counted by this test's rate limit, because the test config does not list it in `rateLimit.ignore`.

To test your real app, import `server` from `#server/main` and use `createTestClient` from [testing](/packages/testing). The real config applies, so set `rateLimit: false` for `NODE_ENV=test` (see [Configure](#configure)), and send the CSRF cookie and header on writes:

```ts
// test/projects.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

const token = 'b'.repeat(48)
const client = createTestClient(server, {
  headers: { cookie: `kitr-csrf=${token}`, 'x-csrf-token': token },
})

it('creates a project through the shield', async () => {
  const res = await client.post<{ id: string }>('/api/projects', { name: 'Billing v2' })
  expect(res.status).toBe(201)
})
```

## Extend

The rate limit stores its counters through a `RateLimitStore`: one method that increments a key and returns the count and when its window resets.

```ts
interface RateLimitStore {
  /** Increment and return the count and when the window resets (ms epoch). */
  hit(key: string, windowMs: number): Promise<{ count: number; resetAt: number }>
}
```

The default memory store counts per process, so with three instances a client gets three times `max`. A Redis store shares the counters. This one uses [ioredis](https://github.com/redis/ioredis) (`pnpm add ioredis`):

```ts
// server/security/redis_rate_limit_store.ts
import type { RateLimitStore } from 'kitr/shield'
import { Redis } from 'ioredis'

export function createRedisRateLimitStore(url: string, prefix = 'acme-app:ratelimit:'): RateLimitStore {
  const redis = new Redis(url)
  return {
    async hit(key, windowMs) {
      const name = prefix + key
      const results = await redis.multi().incr(name).pttl(name).exec()
      const count = Number(results?.[0]?.[1] ?? 1)
      let ttl = Number(results?.[1]?.[1] ?? -1)
      if (ttl < 0) {
        await redis.pexpire(name, windowMs)
        ttl = windowMs
      }
      return { count, resetAt: Date.now() + ttl }
    },
  }
}
```

Register it in the config:

```ts
// config/shield.ts
import { defineConfig } from 'kitr/shield'
import { createRedisRateLimitStore } from '#server/security/redis_rate_limit_store'

export default defineConfig({
  headers: {},
  cors: { origin: ['https://app.acme.com'], credentials: true },
  rateLimit: {
    max: 300,
    windowMs: 60_000,
    store: createRedisRateLimitStore(process.env.REDIS_URL ?? 'redis://localhost:6379'),
  },
  csrf: { ignore: ['/webhooks'] },
})
```

The first hit in a window creates the key and sets its expiry, so Redis deletes the counter when the window ends. See [`RateLimitStore`](/packages/shield/api#ratelimitstore) in the API reference.

## Next steps

- [API reference](/packages/shield/api): every export with its signature.
- [Server](/packages/server): the h3 server the shield attaches to.
- [HTTP](/packages/http): the client that sends the CSRF token for you.
- [Auth](/packages/auth): sessions, sign-in and permissions.
- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/): what each header defends against.


# State API

Source: https://kitr.dev/packages/state/api

`kitr/state` re-exports everything from `zustand` and adds `createKitrStore`.

## createKitrStore

```ts
function createKitrStore<T extends object>(
  options: KitrStoreOptions<T>,
  initializer: StateCreator<T>,
): readonly [useStore, StoreProvider, store]
```

Creates a store that is a singleton in the browser and per-provider on the server.

### Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | required | Used for devtools and as the storage key `kitr:<name>`. |
| `persist` | `boolean \| PersistOptions` | `false` | Save to `localStorage`. An object is passed to Zustand's `persist` middleware; its `name` overrides the storage key. |
| `devtools` | `boolean` | `true` in dev | Connect to Redux DevTools in development. |

### Returns

A tuple. Name the parts whatever suits your store.

| Position | Value | Description |
| --- | --- | --- |
| 0 | `useStore()` / `useStore(selector)` | Hook. Without a selector it returns the whole state. |
| 1 | `StoreProvider` | Component with `children` and optional `initialState: Partial<T>`. Required on the server. |
| 2 | `store` | The browser's `StoreApi<T>`, or `null` on the server. |

### Errors

Calling the hook on the server without a surrounding `StoreProvider` throws:

```
[kitr/state] Store "cart" has no instance on the server. Wrap the tree in its <StoreProvider>.
```

## Re-exports from zustand

`create`, `createStore`, `useStore`, `StateCreator`, `StoreApi` and everything else Zustand exports. Middleware such as `persist`, `devtools` and `createJSONStorage` comes from `zustand/middleware`.


# State

Source: https://kitr.dev/packages/state

Some values belong to the whole app rather than one component: the order Ada is putting together before she submits it, whether the sidebar is open, which currency Linus prefers. `kitr/state` gives you a small store for those values that any component can read and update, and that can remember them across page reloads.

It is [Zustand](https://zustand.docs.pmnd.rs), re-exported, plus one helper, `createKitrStore`, that makes a store safe for server rendering, saves it in the browser when you ask, and connects it to the Redux DevTools in development.

It runs in the browser, and on the server while a page renders. For data a server owns, such as the list of orders or the signed-in user, use [Query](/packages/query) instead.

This guide builds Acme's order draft: the lines Ada adds before she places an order at `app.acme.com`.

## When to use it

Use a store for **client state**: values that live in the browser and that no server owns.

- A draft order or shopping cart before checkout.
- UI preferences such as theme, density, currency or a collapsed sidebar.
- A multi-step wizard's progress.
- A selection shared by distant components, such as the invoices ticked in a table and the bulk-action bar above it.

Don't use a store for **server data** such as Acme's orders, invoices or projects. That belongs in a query (see [Query](/packages/query)), which caches it, refetches it and updates it after a save. A copy in a store goes stale the moment someone else changes the record.

## Install

```sh
kitr add state
```

What `kitr add` does:

- Installs `@kitr/state` and `zustand`.
- Adds `@kitr/state` to `packages` in `kitrrc.ts`. There is no provider to register.
- Writes an empty `app/stores/.gitkeep`, so the folder for your stores exists.
- Adds a `## kitr: state` section to `AGENTS.md`: client state only, `kitr make:store <name>` writes `app/stores/<name>.ts` with `createKitrStore`, and server data belongs in queries.

`kitr add state` asks no questions. The `app`, `fullstack`, `saas`, `desktop` and `mobile` kits include it. To preview the changes without writing them:

```sh
kitr add state --dry-run
```

`kitr remove state` removes the `packages` entry, both dependencies and the `AGENTS.md` section. It leaves `app/stores/` and your stores in place, and lists the files that still import `kitr/state`.

## Configure

`kitr/state` has no config file. Each store takes its options as the first argument of `createKitrStore`:

```ts
// app/stores/preferences.ts
import { createKitrStore } from 'kitr/state'

interface PreferencesState {
  currency: 'USD' | 'EUR'
  setCurrency: (currency: 'USD' | 'EUR') => void
}

export const [usePreferences, PreferencesProvider, preferencesStore] =
  createKitrStore<PreferencesState>(
    {
      name: 'preferences',
      persist: { version: 1 },
      devtools: true,
    },
    (set) => ({
      currency: 'USD',
      setCurrency: (currency) => set({ currency }),
    }),
  )
```

| Option | Default | Description |
| --- | --- | --- |
| `name` | required | The store's name. It labels the store in the Redux DevTools and builds the storage key `kitr:<name>`. |
| `persist` | `false` | `true` saves the whole state to `localStorage`. An object saves it with any of Zustand's [persist options](https://zustand.docs.pmnd.rs/middlewares/persist). Only the browser reads or writes storage. |
| `persist.name` | `'kitr:<name>'` | The storage key. |
| `persist.storage` | `localStorage`, as JSON | Where to save. Use `createJSONStorage(() => sessionStorage)` from `zustand/middleware` for one tab only. |
| `persist.partialize` | the whole state | A function that picks what to save. |
| `persist.version` | `0` | The saved shape's version. Saved data with another version goes through `migrate`, or is dropped without one. |
| `persist.migrate` | none | A function `(saved, version) => state` that upgrades old saved data. |
| `devtools` | `true` | Connects the store to the [Redux DevTools](https://github.com/reduxjs/redux-devtools) extension in development. Set `false` to leave it out. Production builds never connect. |

The second argument is a Zustand state creator: a function that gets `set`, `get` and the store, and returns the initial state with its actions.

`createKitrStore` returns three things, in this order:

| Value | Description |
| --- | --- |
| `useStore` | The hook. `useStore(selector)` returns a slice; `useStore()` returns the whole state. |
| `StoreProvider` | A component that gives its subtree a store. Needed on the server; optional in the browser. Takes `initialState`. |
| `store` | The browser's store instance, for code outside components. `null` on the server. |

Name them after the store, as in `[useOrderDraft, OrderDraftProvider, orderDraftStore]`.

## Create your first store

Put each store in `app/stores/`. This one holds the order Ada is building:

```ts
// app/stores/order-draft.ts
import { createKitrStore } from 'kitr/state'

export interface DraftLine {
  sku: string
  name: string
  price: number
  quantity: number
}

interface OrderDraftState {
  customer: string
  lines: DraftLine[]
  setCustomer: (customer: string) => void
  addLine: (line: Omit<DraftLine, 'quantity'>) => void
  removeLine: (sku: string) => void
  clear: () => void
}

export const [useOrderDraft, OrderDraftProvider, orderDraftStore] =
  createKitrStore<OrderDraftState>({ name: 'order-draft', persist: true }, (set) => ({
    customer: '',
    lines: [],
    setCustomer: (customer) => set({ customer }),
    addLine: (line) =>
      set((state) => {
        const existing = state.lines.find((l) => l.sku === line.sku)
        if (!existing) return { lines: [...state.lines, { ...line, quantity: 1 }] }
        return {
          lines: state.lines.map((l) => (l.sku === line.sku ? { ...l, quantity: l.quantity + 1 } : l)),
        }
      }),
    removeLine: (sku) => set((state) => ({ lines: state.lines.filter((l) => l.sku !== sku) })),
    clear: () => set({ customer: '', lines: [] }),
  }))
```

Then use it from any two components, however far apart:

```tsx
// app/routes/orders/new.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useOrderDraft } from '#app/stores/order-draft'

export const Route = createFileRoute('/orders/new')({
  component: NewOrderPage,
})

function AddLicense() {
  const addLine = useOrderDraft((s) => s.addLine)
  return (
    <button type="button" onClick={() => addLine({ sku: 'acme-seat', name: 'Acme seat', price: 12 })}>
      Add a seat
    </button>
  )
}

function DraftCount() {
  const count = useOrderDraft((s) => s.lines.reduce((sum, l) => sum + l.quantity, 0))
  return <p>{count} items in this order</p>
}

function NewOrderPage() {
  return (
    <main>
      <DraftCount />
      <AddLicense />
    </main>
  )
}
```

Open `/orders/new` and press **Add a seat** three times: the count reads `3 items in this order`. Reload the page and it still reads 3, because `persist: true` saved the draft to `localStorage` under `kitr:order-draft`.

`kitr make:store` writes a starter store for you; see [Commands](#commands).

## Read a value in a component

Pass a selector to the hook. The component re-renders only when the selected value changes, so `DraftCount` ignores a change to `customer`:

```tsx
// app/features/orders/draft-customer.tsx
import { useOrderDraft } from '#app/stores/order-draft'

export function DraftCustomer() {
  const customer = useOrderDraft((s) => s.customer)
  const setCustomer = useOrderDraft((s) => s.setCustomer)
  return (
    <label>
      Customer
      <input value={customer} onChange={(e) => setCustomer(e.target.value)} />
    </label>
  )
}
```

Actions are part of the state, and they never change, so selecting one never causes a re-render.

Calling the hook with no selector returns the whole state. The component then re-renders on every change to any field, so keep that for small stores or for debugging:

```tsx
// app/features/orders/draft-debug.tsx
import { useOrderDraft } from '#app/stores/order-draft'

export function DraftDebug() {
  const draft = useOrderDraft()
  return <pre>{JSON.stringify({ customer: draft.customer, lines: draft.lines }, null, 2)}</pre>
}
```

## Select several values at once

A selector that builds a new object or array on every call, such as `(s) => ({ customer: s.customer, count: s.lines.length })`, returns a different value each time, and React keeps re-rendering. Either call the hook once per value, or wrap the selector in Zustand's `useShallow`, which compares the result field by field:

```tsx
// app/features/orders/draft-header.tsx
import { useShallow } from 'zustand/react/shallow'
import { useOrderDraft } from '#app/stores/order-draft'

export function DraftHeader() {
  const { customer, count } = useOrderDraft(
    useShallow((s) => ({ customer: s.customer, count: s.lines.length })),
  )
  return (
    <h2>
      Draft for {customer || 'a new customer'} ({count} lines)
    </h2>
  )
}
```

Derived numbers and strings are safe without it: `(s) => s.lines.length` returns the same number until the length changes.

## Change state with actions

Inside the creator, `set` merges a partial state into the current one. Pass an object when the new value does not depend on the old one, and a function when it does:

```ts
// app/stores/invoice-selection.ts
import { createKitrStore } from 'kitr/state'

interface InvoiceSelectionState {
  selected: string[]
  toggle: (invoiceId: string) => void
  selectAll: (invoiceIds: string[]) => void
  clear: () => void
  isSelected: (invoiceId: string) => boolean
}

export const [useInvoiceSelection, InvoiceSelectionProvider, invoiceSelectionStore] =
  createKitrStore<InvoiceSelectionState>({ name: 'invoice-selection' }, (set, get) => ({
    selected: [],
    toggle: (id) =>
      set((s) => ({
        selected: s.selected.includes(id) ? s.selected.filter((x) => x !== id) : [...s.selected, id],
      })),
    selectAll: (ids) => set({ selected: ids }),
    clear: () => set({ selected: [] }),
    isSelected: (id) => get().selected.includes(id),
  }))
```

`get()` reads the current state inside an action. Keep the logic in actions rather than in components, so every caller changes the state the same way.

Don't mutate the state in place (`s.selected.push(id)`). `set` compares by reference, so a mutated array looks unchanged and nothing re-renders. Return a new array or object.

## Read and change state outside React

The third value is the browser's store instance. Use it in code that is not a component: an event handler set up at startup, a route loader, a mutation's `onSuccess`:

```ts
// app/features/orders/place-order.ts
import { orderDraftStore } from '#app/stores/order-draft'

export async function placeDraftOrder() {
  const draft = orderDraftStore?.getState()
  if (!draft || draft.lines.length === 0) return
  await fetch('/api/orders', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ customer: draft.customer, lines: draft.lines }),
  })
  orderDraftStore?.getState().clear()
}
```

| Method | What it does |
| --- | --- |
| `getState()` | Returns the current state, actions included. |
| `setState(partial)` | Merges `partial` (or the result of a function of the state) into the state. |
| `setState(state, true)` | Replaces the whole state. Include the actions, or they are gone. |
| `subscribe(listener)` | Calls `listener(state, previous)` after every change. Returns a function that stops it. |
| `getInitialState()` | Returns the state the creator first produced. |

`subscribe` lets code outside React react to changes. This keeps the page title in step with the draft:

```ts
// app/features/orders/draft-title.ts
import { orderDraftStore } from '#app/stores/order-draft'

export const stopDraftTitle = orderDraftStore?.subscribe((state, previous) => {
  if (state.lines.length !== previous.lines.length)
    document.title = state.lines.length ? `(${state.lines.length}) Acme` : 'Acme'
})
```

The store is `null` on the server, which is why every call above uses `?.`. Code that only ever runs in the browser, such as a click handler, can assert it with `orderDraftStore!`.

## Save state in the browser

With `persist: true`, the whole state is saved to `localStorage` under `kitr:<name>` after every change, and restored when the page loads. The saved value is JSON with the state and a version:

```ts
// In the browser console after adding one seat
JSON.parse(localStorage.getItem('kitr:order-draft')!)
// => { state: { customer: '', lines: [{ sku: 'acme-seat', name: 'Acme seat', price: 12, quantity: 1 }] }, version: 0 }
```

Functions are not saved, because JSON cannot hold them; the actions come from the creator each time.

Pass an object to control what is saved. `partialize` picks the fields; here the draft's lines survive a reload but the customer does not:

```ts
// app/stores/order-draft.ts
import { createKitrStore } from 'kitr/state'
import type { DraftLine } from './types'

interface OrderDraftState {
  customer: string
  lines: DraftLine[]
  clear: () => void
}

export const [useOrderDraft, OrderDraftProvider, orderDraftStore] =
  createKitrStore<OrderDraftState>(
    {
      name: 'order-draft',
      persist: {
        partialize: (state) => ({ lines: state.lines }),
      },
    },
    (set) => ({
      customer: '',
      lines: [],
      clear: () => set({ customer: '', lines: [] }),
    }),
  )
```

> **Warning**
> `localStorage` is readable by any script on the page and stays on the device after sign-out. Never persist tokens, passwords or personal data in a store. Use [Secure storage](/packages/secure-storage) for secrets.

## Change the saved shape

When the state's shape changes, data saved by the old version no longer fits. Bump `version`, and give `migrate` a function that upgrades old data. Without `migrate`, data from another version is ignored and the store starts from its initial state:

```ts
// app/stores/preferences.ts
import { createKitrStore } from 'kitr/state'

interface PreferencesState {
  currency: 'USD' | 'EUR'
  density: 'comfortable' | 'compact'
  setDensity: (density: 'comfortable' | 'compact') => void
}

export const [usePreferences, PreferencesProvider, preferencesStore] =
  createKitrStore<PreferencesState>(
    {
      name: 'preferences',
      persist: {
        version: 2,
        migrate: (saved, version) => {
          const old = saved as { currency?: 'USD' | 'EUR'; compact?: boolean }
          // Version 1 stored a boolean `compact`; version 2 stores `density`.
          if (version < 2) return { currency: old.currency ?? 'USD', density: old.compact ? 'compact' : 'comfortable' }
          return old as Partial<PreferencesState>
        },
      },
    },
    (set) => ({
      currency: 'USD',
      density: 'comfortable',
      setDensity: (density) => set({ density }),
    }),
  )
```

## Save for one tab only

`sessionStorage` keeps state for one tab and clears it when the tab closes. It suits a wizard Grace should be able to run in two tabs at once without them mixing:

```ts
// app/stores/import-wizard.ts
import { createKitrStore } from 'kitr/state'
import { createJSONStorage } from 'zustand/middleware'

interface ImportWizardState {
  step: 1 | 2 | 3
  fileName: string | null
  next: () => void
  back: () => void
}

export const [useImportWizard, ImportWizardProvider, importWizardStore] =
  createKitrStore<ImportWizardState>(
    { name: 'import-wizard', persist: { storage: createJSONStorage(() => sessionStorage) } },
    (set) => ({
      step: 1,
      fileName: null,
      next: () => set((s) => ({ step: Math.min(3, s.step + 1) as 1 | 2 | 3 })),
      back: () => set((s) => ({ step: Math.max(1, s.step - 1) as 1 | 2 | 3 })),
    }),
  )
```

## Seed a store for a page

`StoreProvider` takes `initialState`, which is merged over the creator's state when the provider first mounts. Use it to start a store from data a loader fetched, such as the customer of the order Linus is editing:

```tsx
// app/routes/orders/$orderId.edit.tsx
import { createFileRoute } from '@tanstack/react-router'
import { OrderDraftProvider } from '#app/stores/order-draft'
import { orderQuery } from '#app/features/orders/queries'
import { DraftEditor } from '#app/features/orders/draft-editor'

export const Route = createFileRoute('/orders/$orderId/edit')({
  loader: ({ context, params }) => context.queryClient.ensureQueryData(orderQuery.options(params.orderId)),
  component: EditOrderPage,
})

function EditOrderPage() {
  const order = Route.useLoaderData()
  return (
    <OrderDraftProvider initialState={{ customer: order.customer }}>
      <DraftEditor />
    </OrderDraftProvider>
  )
}
```

In the browser the store is shared by the whole app, so `initialState` writes into that one store with `setState` when the provider mounts. It overrides values restored from storage, and every component using the store sees it, inside the provider or not. On the server each provider builds its own store with `initialState` already applied, so the page renders with it.

## Render on the server

On the server, one process renders pages for many users at once. A store created at module level would be shared by all of them, and Ada's draft could render in Grace's page. `createKitrStore` prevents that:

- **In the browser**, the store is one module-level instance. The hook reads it without any provider.
- **On the server**, there is no module-level instance. Each `<StoreProvider>` creates a fresh store for its render, and storage is never touched.

If a page renders on the server (a `web` platform in `ssr` or `static` mode), wrap the part of the tree that reads the store:

```tsx
// app/routes/__root.tsx
import { createRootRoute, Outlet } from '@tanstack/react-router'
import { OrderDraftProvider } from '#app/stores/order-draft'

export const Route = createRootRoute({
  component: () => (
    <OrderDraftProvider>
      <Outlet />
    </OrderDraftProvider>
  ),
})
```

Without a provider, a server render fails with:

```txt
[kitr/state] Store "order-draft" has no instance on the server. Wrap the tree in its <StoreProvider>.
```

In a client-only app (`spa` mode, desktop, mobile) you can skip the provider entirely.

A saved store renders its initial state on the server, because the server cannot read the browser's storage, and its saved state in the browser. React reports a hydration mismatch for the elements that differ. Render saved values only after the component mounts:

```tsx
// app/features/orders/draft-badge.tsx
import { useEffect, useState } from 'react'
import { useOrderDraft } from '#app/stores/order-draft'

export function DraftBadge() {
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])
  const count = useOrderDraft((s) => s.lines.length)
  return <span>{mounted && count > 0 ? `${count} in draft` : null}</span>
}
```

## Use plain Zustand

`kitr/state` re-exports `zustand` unchanged, so `create`, `createStore`, `useStore` and the types work as in the [Zustand docs](https://zustand.docs.pmnd.rs). Middleware comes from `zustand/middleware`. A store made with `create` is a module-level singleton on the server too, so use it only in client-only apps or for state that is the same for every user:

```ts
// app/stores/toasts.ts
import { create } from 'kitr/state'

interface ToastState {
  messages: string[]
  push: (message: string) => void
}

export const useToasts = create<ToastState>()((set) => ({
  messages: [],
  push: (message) => set((s) => ({ messages: [...s.messages, message] })),
}))
```

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:store <name>` | Writes `app/stores/<name>.ts` with a `createKitrStore` store: a `count`, an `increment` and a `reset` action, not persisted. |

```sh
kitr make:store order-draft
```

It writes `app/stores/order_draft.ts`. The file name is snake case; the exports are camel and pascal case:

```ts
// app/stores/order_draft.ts
import { createKitrStore } from 'kitr/state'

interface OrderDraftState {
  count: number
  increment: () => void
  reset: () => void
}

export const [useOrderDraftStore, OrderDraftStoreProvider, orderDraftStore] = createKitrStore<OrderDraftState>(
  { name: 'order_draft', persist: false },
  (set) => ({
    count: 0,
    increment: () => set((s) => ({ count: s.count + 1 })),
    reset: () => set({ count: 0 }),
  }),
)
```

Replace the state with your own. Pass `--force` to overwrite an existing file. To change the template for your project, run `kitr eject stub store` and edit `stubs/store.ts`.

## Testing

In a DOM test (Vitest with `happy-dom` or `jsdom`), the store is the browser singleton, so it keeps its state from one test to the next. Reset it in `beforeEach` with `setState`, and clear `localStorage` if the store persists:

```tsx
// app/stores/order-draft.test.tsx
import { act, render, screen } from '@testing-library/react'
import { beforeEach, describe, expect, it } from 'vitest'
import { orderDraftStore, useOrderDraft } from './order-draft'

function DraftCount() {
  const count = useOrderDraft((s) => s.lines.reduce((sum, l) => sum + l.quantity, 0))
  return <p>{count} items</p>
}

describe('order draft', () => {
  beforeEach(() => {
    localStorage.clear()
    orderDraftStore!.setState({ customer: '', lines: [] })
  })

  it('adds a line and bumps its quantity', () => {
    const { addLine } = orderDraftStore!.getState()
    addLine({ sku: 'acme-seat', name: 'Acme seat', price: 12 })
    addLine({ sku: 'acme-seat', name: 'Acme seat', price: 12 })
    expect(orderDraftStore!.getState().lines).toEqual([
      { sku: 'acme-seat', name: 'Acme seat', price: 12, quantity: 2 },
    ])
  })

  it('re-renders components that read it', () => {
    render(<DraftCount />)
    expect(screen.getByText('0 items')).toBeTruthy()
    act(() => orderDraftStore!.getState().addLine({ sku: 'acme-seat', name: 'Acme seat', price: 12 }))
    expect(screen.getByText('1 items')).toBeTruthy()
  })

  it('saves the draft under kitr:order-draft', () => {
    act(() => orderDraftStore!.getState().setCustomer('Ada'))
    expect(JSON.parse(localStorage.getItem('kitr:order-draft')!).state.customer).toBe('Ada')
  })
})
```

Wrap changes made outside React in `act()` when a component is rendered, so React applies the update before you assert.

To test what the server renders, run the test in the `node` environment, where there is no singleton, and render through the provider:

```tsx
// app/stores/order-draft.server.test.tsx
// @vitest-environment node
import { renderToString } from 'react-dom/server'
import { expect, it } from 'vitest'
import { OrderDraftProvider, orderDraftStore, useOrderDraft } from './order-draft'

function Customer() {
  return <p>{useOrderDraft((s) => s.customer) || 'nobody'}</p>
}

it('gives every server render its own store', () => {
  expect(orderDraftStore).toBeNull()
  const ada = renderToString(
    <OrderDraftProvider initialState={{ customer: 'Ada' }}>
      <Customer />
    </OrderDraftProvider>,
  )
  const grace = renderToString(
    <OrderDraftProvider>
      <Customer />
    </OrderDraftProvider>,
  )
  expect(ada).toContain('Ada')
  expect(grace).toContain('nobody')
})
```

## Devtools

In development, every store connects to the [Redux DevTools](https://github.com/reduxjs/redux-devtools) browser extension under its `name`. Each `set` shows up as an action with the state before and after, and you can step back through them. The connection is skipped in production builds, on the server, and for stores created with `devtools: false`.

## Next steps

- [API reference](/packages/state/api)
- [Zustand docs](https://zustand.docs.pmnd.rs): everything there works as written, imported from `kitr/state`.
- [Zustand persist options](https://zustand.docs.pmnd.rs/middlewares/persist): every option `persist` accepts.
- [Query](/packages/query): where server data belongs.
- [Forms](/packages/forms): form state, validation and server errors, without a store.


# Storage API

Source: https://kitr.dev/packages/storage/api

Every export of `kitr/storage`, `kitr/storage/react`, `kitr/storage/server`, `kitr/storage/provider`, read from the published type definitions. The [guide](/packages/storage) shows them in use.

## kitr/storage

### createAsyncStorageDriver

```ts
function createAsyncStorageDriver(options: {
  name: string;
  load(): Promise<Record<string, string>>;
  write(key: string, raw: string): Promise<void>;
  erase(key: string): Promise<void>;
  onError?: (error: unknown) => void;
}): StorageDriver;
```

Build a driver over an async native store. `load` runs once at boot and fills the cache;
`write`/`erase` run in the background after each change, so reads stay synchronous.

### createMemoryKvDriver

```ts
function createMemoryKvDriver(): KvDriver;
```

The default `kv` driver: a Map with ttl support. Values are lost on restart and not shared between processes.

### createMemoryStorageDriver

```ts
function createMemoryStorageDriver(name?: string): StorageDriver;
```

In-memory driver: tests, the server, and `session` items on native platforms.

### createWebStorageDriver

```ts
function createWebStorageDriver(name: StorageArea): StorageDriver | null;
```

Web Storage as a driver. Null outside a browser, so items fall back to their defaults.

### defineCookie

```ts
function defineCookie<T = string>(name: string, options: CookieItemOptions<T>): CookieItem<T>;
```

A typed cookie, readable on both sides and writable from the browser or the server.

```ts
const locale = defineCookie('locale', { default: 'en', maxAge: 60 * 60 * 24 * 365 })
locale.get()                      // client: document.cookie
locale.get(request.headers)       // server: any Headers / Cookie header string
locale.set('de')                  // client
cookies(event).set(locale, 'de')  // server (kitr/storage/server)
```

### defineKv

```ts
function defineKv<T>(name: string, options: KvItemOptions<T>): KvItem<T>;
```

A value shared by the whole app on the server (`scope: 'app'`): feature state, counters,
cached lookups. Backed by memory unless `config/storage.ts` sets a `kv` driver
(Redis, Cloudflare KV, a file... anything with get/set/remove).

```ts
const banner = defineKv('banner', { default: { text: '' } })
await banner.set({ text: 'Maintenance at 22:00' })
```

### defineStorage

```ts
function defineStorage<T>(name: string, options: StorageItemOptions<T>): StorageItem<T>;
```

A typed item in localStorage or sessionStorage.

```ts
const sidebar = defineStorage('sidebar', { default: { open: true } })
sidebar.get().open; sidebar.set((s) => ({ ...s, open: false }))
```
Safe everywhere: on the server (or when storage is blocked) `get()` returns the default
and `set()` is a no-op, so the same module renders on both sides.

### getKvDriver

```ts
function getKvDriver(): KvDriver;
```

The active `kv` driver, creating the in-memory one on first use.

### getStorageDriver

```ts
function getStorageDriver(name: StorageArea): StorageDriver | null;
```

The driver behind an area: the platform driver, Web Storage, or null on the server.

### listStorage

```ts
function listStorage(name: StorageArea): Array<{
  key: string;
  raw: string | null;
}>;
```

Every key in an area, for the devtools panel.

### logStorage

```ts
function logStorage(app: KitrApp, label: string, data?: unknown): void;
```

Write a line to the devtools `storage` channel. Does nothing when devtools are off.

### notifyCookiesChanged

```ts
function notifyCookiesChanged(): void;
```

Call after something else wrote `document.cookie` so `useCookie()` re-reads.

### parseCookies

```ts
function parseCookies(header: string | null | undefined): Record<string, string>;
```

Parse a `Cookie` header into a map. Values are decoded with decodeURIComponent.

### removeStorageKey

```ts
function removeStorageKey(name: StorageArea, key: string): void;
```

Delete one raw key from an area and notify subscribers. Used by the devtools panel.

### serializeCookie

```ts
function serializeCookie(name: string, value: string | null, options?: CookieOptions): string;
```

Build a `Set-Cookie` value. `value === null` expires the cookie.

### setCookieDefaults

```ts
function setCookieDefaults(defaults: Omit<CookieOptions, 'name'>): void;
```

Attributes merged into every cookie this app writes. The provider sets them from `cookie` in config.

### setKvDriver

```ts
function setKvDriver(driver: KvDriver): void;
```

Set by the storage provider from `config/storage.ts` (`kv`). Any object with async get, set and remove over strings works.

### setStorageDriver

```ts
function setStorageDriver(driver: StorageDriver, areas?: {
  local?: StorageDriver;
  session?: StorageDriver;
}): void;
```

Replace the Web Storage backing with a platform driver. Called by the storage provider when a
platform registered one (`app.drivers.register('storage', driver)`); `session` items keep an
in-memory driver unless `areas` says otherwise.

### setStoragePrefix

```ts
function setStoragePrefix(prefix: string): void;
```

Set by the provider from `config/storage.ts`; items created later pick it up.

### defineConfig

```ts
const defineConfig: <const C extends StorageConfig>(config: C) => C;
```

Type-checks `config/storage.ts`. Returns the object unchanged.

### jsonCodec

```ts
const jsonCodec: <T>() => Codec<T>;
```

The default codec for objects: `JSON.stringify` and `JSON.parse`.

### stringCodec

```ts
const stringCodec: Codec<string>;
```

Stores strings as they are, with no quotes. The default for cookies whose default is a string.

### Codec

```ts
interface Codec<T> {
  /** Value to stored string. */
  encode(value: T): string;
  /** Stored string to value. Throwing makes the item fall back to its default. */
  decode(raw: string): T;
}
```

Turns a value into the string that is stored and back. Pass one as `codec` to change the format.

### CookieItem

```ts
interface CookieItem<T> {
  /** The name it was defined with, without the config prefix. */
  readonly name: string;
  /** Returned when the cookie is missing or invalid. */
  readonly default: T;
  /** The attributes given to `defineCookie`. */
  readonly options: CookieOptions;
  /** Read from `document.cookie`, or from the given source on the server. */
  get(source?: CookieSource): T;
  /** Write `document.cookie` (client). On the server use `cookies(event).set(item, value)`. */
  set(value: T, options?: CookieOptions): void;
  /** Expire the cookie in the browser. A no-op on the server. */
  remove(): void;
  /** Fires after `set`, `remove` or `notifyCookiesChanged()` in this tab. */
  subscribe(listener: (value: T) => void): () => void;
  /** The `Set-Cookie` header value for this item. */
  serialize(value: T | null, options?: CookieOptions): string;
  /** Parse one raw cookie value into T (or the default). */
  decode(raw: string | undefined): T;
}
```

A typed cookie returned by `defineCookie`, readable on both sides.

### CookieItemOptions

```ts
interface CookieItemOptions<T> extends CookieOptions {
  /** Returned when the cookie is missing or invalid. */
  default: T;
  /** Validate the decoded value (Standard Schema). Invalid → default. */
  schema?: StandardSchemaV1<unknown, T>;
  /** Default: JSON for objects, plain string for string defaults. */
  codec?: Codec<T>;
}
```

Options for `defineCookie`: the default, validation, format, and the cookie attributes.

### CookieOptions

```ts
interface CookieOptions {
  /** URL path the cookie is sent for. */
  path?: string;
  /** Domain the cookie is sent to, e.g. `.acme.com` to share it with subdomains. */
  domain?: string;
  /** Seconds. */
  maxAge?: number;
  /** Absolute expiry date. */
  expires?: Date;
  /** Send only over HTTPS. Forced on when `sameSite` is `none`. */
  secure?: boolean;
  /** Server-set cookies only; the browser cannot write httpOnly cookies. */
  httpOnly?: boolean;
  /** Cross-site sending rule. */
  sameSite?: 'lax' | 'strict' | 'none';
}
```

Attributes written into `Set-Cookie`. `path: '/'` and `sameSite: 'lax'` apply unless overridden.

### KvDriver

```ts
interface KvDriver {
  /** The raw string under `key`, or null when missing or expired. */
  get(key: string): Promise<string | null>;
  /** Store a raw string; `ttl` is in milliseconds. */
  set(key: string, raw: string, options?: {
    ttl?: number;
  }): Promise<void>;
  /** Delete one key. */
  remove(key: string): Promise<void>;
  /** Keys starting with `prefix`. Optional; kitr does not call it. */
  keys?(prefix?: string): Promise<string[]>;
}
```

The server-side store behind `defineKv`: anything async with get, set and remove over strings.
Wrap Redis, Cloudflare KV or a file in this shape and pass it as `kv` in `config/storage.ts`.

### KvItem

```ts
interface KvItem<T> {
  /** The name it was defined with, without the config prefix. */
  readonly key: string;
  /** Returned when the key is missing, expired or invalid. */
  readonly default: T;
  /** The stored value, or the default. */
  get(): Promise<T>;
  /** Store a value, or compute it from the current one. `ttl` overrides the item's default. */
  set(value: T | ((current: T) => T), options?: {
    ttl?: number;
  }): Promise<void>;
  /** Delete the stored value. */
  remove(): Promise<void>;
}
```

A typed server-side value returned by `defineKv`. Every method is async.

### KvItemOptions

```ts
interface KvItemOptions<T> {
  /** Returned when the key is missing, expired or invalid. */
  default: T;
  /** Validate what comes back from the driver (Standard Schema). Invalid → default. */
  schema?: StandardSchemaV1<unknown, T>;
  /** Format of the stored string. Default: JSON. */
  codec?: Codec<T>;
  /** Milliseconds to keep a value. */
  ttl?: number;
}
```

Options for `defineKv`: the default, validation, format and a default ttl.

### StorageConfig

```ts
interface StorageConfig {
  /** Prefix for every storage key and cookie name, e.g. `myapp:`. Default none. */
  prefix?: string;
  /** Defaults merged into every cookie. */
  cookie?: Omit<CookieOptions, 'name'>;
  /** Server-side key-value store behind `defineKv` (app scope). Default: in-memory. */
  kv?: KvDriver;
}
```

Options for `config/storage.ts`: a key prefix, cookie defaults and the server-side kv driver.

### StorageDriver

```ts
interface StorageDriver {
  /** Shown in the devtools log, e.g. `web:local` or `capacitor:preferences`. */
  name: string;
  /** Load every stored key into memory before the first render. */
  hydrate?(): Promise<void>;
  /** The raw string stored under `key`, or null. Must answer synchronously. */
  get(key: string): string | null;
  /** Store a raw string. May persist in the background. */
  set(key: string, raw: string): void;
  /** Delete one key. */
  remove(key: string): void;
  /** Every stored key, for the devtools panel. */
  keys(): string[];
  /** Changes made elsewhere (another tab, the native side). */
  subscribe?(listener: (key: string | null) => void): () => void;
}
```

What a platform supplies to back `defineStorage` items: Capacitor Preferences on mobile,
the Tauri store or an Electron JSON file on desktop, Web Storage in the browser.
Reads are synchronous from a cache `hydrate()` fills at boot; writes go through in the background.

### StorageItem

```ts
interface StorageItem<T> {
  /** The name it was defined with, without the config prefix. */
  readonly key: string;
  /** Which area it lives in. */
  readonly area: StorageArea;
  /** The stored value, or the default when it is missing, invalid, expired or on the server. */
  get(): T;
  /** Store a value, or compute it from the current one. A no-op on the server. */
  set(value: T | ((current: T) => T)): void;
  /** Delete the stored value so `get()` returns the default. */
  remove(): void;
  /** Fires on set/remove here and in other tabs (`storage` event). */
  subscribe(listener: (value: T) => void): () => void;
  /** The default, for server snapshots. */
  readonly default: T;
}
```

A typed value in local or session storage, returned by `defineStorage`.

### StorageItemOptions

```ts
interface StorageItemOptions<T> {
  /** Returned when the key is missing, unparsable, invalid or on the server. */
  default: T;
  /** Where it is stored. Default `local`. */
  area?: StorageArea;
  /** Validate what comes back from storage (Standard Schema: zod, valibot...). Invalid → default. */
  schema?: StandardSchemaV1<unknown, T>;
  /** Format of the stored envelope. Default: JSON. */
  codec?: Codec<T>;
  /** Bump when the shape changes; stored values with another version are migrated or dropped. */
  version?: number;
  /** Converts a value stored under an older `version`. Without it, old values are dropped. */
  migrate?: (raw: unknown, fromVersion: number) => T;
  /** Keep this many ms, then treat as missing. Stored beside the value. */
  ttl?: number;
}
```

Options for `defineStorage`: the default, the area, and how stored values are checked.

### CookieSource

```ts
type CookieSource = string | null | undefined | Headers | {
  cookie?: string | null;
};
```

Anything that can hold cookies: a `Cookie` header string, a Headers object or `document`.

### StorageArea

```ts
type StorageArea = 'local' | 'session';
```

`local` keeps a value until it is cleared; `session` keeps it for the current tab.

## kitr/storage/react

### CookieHeader

```ts
function CookieHeader({ value, children }: {
  value: string | null | undefined;
  children: ReactNode;
}): import("react").FunctionComponentElement<import("react").ProviderProps<string | null | undefined>>;
```

Gives `useCookie()` the request's `Cookie` header during server rendering, so the first
HTML shows the stored value instead of the default. Wrap the tree once, in the root route.

### useCookie

```ts
function useCookie<T>(item: CookieItem<T>): [
  T,
  (value: T) => void,
  () => void
];
```

Read and write a cookie from a component. On the server the value comes from
`<CookieHeader>` when present, otherwise the default.

### useStorage

```ts
function useStorage<T>(item: StorageItem<T>): [
  T,
  (value: T | ((current: T) => T)) => void,
  () => void
];
```

Read and write a storage item from a component. Hydration-safe: the server (and the first
client render) see the default, then the stored value applies, so markup always matches.

## kitr/storage/server

### cookies

```ts
function cookies(event: CookieEventLike): ServerCookies;

function cookies(request: Request, responseHeaders: Headers): ServerCookies;
```

Typed cookies on the server: `cookies(event)` in a controller or middleware,
`cookies(request, responseHeaders)` anywhere you only have the Fetch primitives.

### CookieEventLike

```ts
interface CookieEventLike {
  /** The request; only its headers are read. */
  req: {
    headers: Headers;
  };
  /** The response; `Set-Cookie` headers are appended here. */
  res: {
    headers: Headers;
  };
}
```

The parts of an h3 v2 event (or anything request/response shaped) that cookies need.

### ServerCookies

```ts
interface ServerCookies {
  /** The item's value from the request's `Cookie` header, or its default. */
  get<T>(item: CookieItem<T>): T;
  /** Appends a `Set-Cookie` header; `httpOnly` and the other item options apply. */
  set<T>(item: CookieItem<T>, value: T, options?: CookieOptions): void;
  /** Appends a `Set-Cookie` header that expires the cookie. */
  remove(item: CookieItem<unknown>): void;
  /** The raw `Cookie` header, for `<CookieHeader>` during SSR. */
  readonly header: string | null;
}
```

Typed cookie access for one request, returned by `cookies()`.

## kitr/storage/provider

### storageProvider

```ts
const storageProvider: import("@kitr/core").KitrProvider;
```

Applies `config/storage.ts` (key prefix, cookie defaults, kv driver), switches `defineStorage`
items to the platform's native driver when one is registered, hydrates it before the first
render, and contributes the Storage panel to the devtools.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Storage

Source: https://kitr.dev/packages/storage

Every app remembers a few things between visits: a collapsed sidebar, the last orders someone searched for, the language they picked. `kitr/storage` lets you declare each of those values once, with a type and a default, and then read and write it anywhere without touching `localStorage` or `document.cookie` yourself. Bad, old or missing values fall back to the default, other tabs stay in sync, and server rendering never breaks.

It is built on [Web Storage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API) and [HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies), and adds types, schema validation, versions with migrations, expiry, hydration-safe React hooks, and a native store on desktop and mobile. Storage items run in the browser; cookies run on both sides, and `defineKv` keeps a value on the server.

Don't use it for login tokens or other secrets: anything in Web Storage is readable by every script on the page. Use [Secure storage](/packages/secure-storage) for those.

This guide follows Acme's order dashboard at `app.acme.com`: Ada collapses the sidebar, searches for orders, switches the language to German, and the server shows a maintenance banner.

## When to use it

Use storage for **small values the user's device owns**: preferences, recent searches, a dismissed notice, a draft. They survive a reload, are read synchronously, and are not shared with other devices.

Use [State](/packages/state) for values that only live while the page is open, and [Query](/packages/query) for data the server owns, such as the orders themselves. Copying server data into storage means you now own keeping it fresh. To keep loaded server data on the device for offline use, use [Offline](/packages/offline), which persists the query cache for you.

## Install

```sh
kitr add storage
```

What `kitr add` does:

- Installs `@kitr/storage`.
- Adds `() => import('@kitr/storage/provider')` to `providers` in `kitrrc.ts`.
- Adds `@kitr/storage` to `packages` in `kitrrc.ts`.
- Writes `config/storage.ts` (shown under [Configure](#configure)).
- Writes `app/storage.ts` with three sample values: `sidebar`, `recentSearches` and `localeCookie`. In a server-only project it writes only `localeCookie`.
- Adds a `## kitr: storage` section to `AGENTS.md`: declare every persisted value in `app/storage.ts`, never read `localStorage` or `document.cookie` directly, use `useStorage` and `useCookie` in components and `cookies(event)` on the server, and add `schema`, `version` with `migrate`, or `ttl` when needed. A server-only project gets one line about `cookies(ctx.event)` instead.

`kitr add storage` asks no questions and adds no environment variables or scripts. It does not overwrite `config/storage.ts` or `app/storage.ts` when they exist.

The `app`, `fullstack`, `saas`, `site`, `realtime`, `desktop` and `mobile` kits include it. The [Desktop](/packages/desktop) and [Mobile](/packages/mobile) platforms require it, so adding either platform adds storage too.

The generated `app/storage.ts` in a project with React:

```ts
// app/storage.ts
import { defineCookie, defineStorage } from 'kitr/storage'

/**
 * Every persisted value, in one file, typed. Components read them with
 * `useStorage(item)` / `useCookie(item)` from kitr/storage/react; plain code with `item.get()`.
 */
export const sidebar = defineStorage('sidebar', { default: { collapsed: false } })

export const recentSearches = defineStorage<string[]>('recent-searches', {
  default: [],
  area: 'session',
  version: 1,
})

/** Readable on the server too (`localeCookie.get(request.headers)`), so SSR picks the right locale. */
export const localeCookie = defineCookie('locale', { default: 'en', maxAge: 60 * 60 * 24 * 365 })
```

`kitr remove storage` reverses every step above and deletes `config/storage.ts`. It leaves `app/storage.ts`, because you have probably edited it, and lists the files that still import `kitr/storage` so you can remove them by hand.

## Configure

`kitr add storage` writes this file. The prefix comes from the `name` in your `package.json`, without its scope; for a project named `acme` it is:

```ts
// config/storage.ts
import { defineConfig } from 'kitr/storage'

export default defineConfig({
  // Prefixes every storage key and cookie name so several apps on one origin never collide.
  prefix: 'acme:',
  cookie: { path: '/', sameSite: 'lax', secure: import.meta.env?.PROD ?? false },
})
```

| Option | Default | Description |
| --- | --- | --- |
| `prefix` | `''` | Added in front of every storage key, cookie name and kv key. `sidebar` is stored as `acme:sidebar`. |
| `cookie` | `{}` | Attributes merged into every cookie this app writes. An item's own options and the options passed to `set()` win over these. |
| `cookie.path` | `'/'` | The URL path a cookie is sent for. |
| `cookie.domain` | none | The domain a cookie is sent to. `.acme.com` shares it with every subdomain. |
| `cookie.maxAge` | none | Lifetime in seconds. Without `maxAge` or `expires`, a cookie lasts until the browser closes. |
| `cookie.expires` | none | An absolute expiry `Date`. |
| `cookie.secure` | `false` | Send only over HTTPS. Always on when `sameSite` is `'none'`. |
| `cookie.httpOnly` | `false` | Hide the cookie from browser scripts. Only cookies set by the server can be `httpOnly`. |
| `cookie.sameSite` | `'lax'` | `'lax'`, `'strict'` or `'none'`. |
| `kv` | in-memory | The driver behind `defineKv` on the server. See [Write a kv driver](#write-a-kv-driver). |

`kitr/storage` adds no environment variables. `import.meta.env?.PROD` is Vite's production flag, so cookies are `Secure` in production builds and work over plain `http://localhost` in development.

The provider applies this file in `register()`: it sets the prefix, the cookie defaults and the kv driver, then switches storage items to the platform's native store when a platform registered one. Items read the prefix every time they touch storage, so values defined before the provider ran still pick it up.

Changing `prefix` in a live app makes every saved value look missing, because the keys change. Users see the defaults again; nothing is migrated.

## Save your first value

Read and write a value from a component with `useStorage`. It returns the value, a setter and a remover, like `useState`:

```tsx
// app/components/sidebar-toggle.tsx
import { useStorage } from 'kitr/storage/react'
import { sidebar } from '#app/storage'

export function SidebarToggle() {
  const [state, setState] = useStorage(sidebar)
  return (
    <button type="button" onClick={() => setState((s) => ({ collapsed: !s.collapsed }))}>
      {state.collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
    </button>
  )
}
```

Put `<SidebarToggle />` in your layout and click it. The label changes to "Expand sidebar". Reload the page: it still says "Expand sidebar". In the browser's devtools, under Application → Local Storage, you see one key:

```text
acme:sidebar    {"v":1,"d":{"collapsed":true}}
```

Every storage item is saved as a small envelope: `v` is the item's version, `d` is the data, and `e` is the expiry time when the item has a `ttl`. You never read the envelope yourself; `get()` unwraps it.

The setter takes a value or a function of the current value. The third element, `remove`, deletes the key so the item reads its default again.

## Read and write outside React

Every item has the same three methods outside components, so services, route loaders and event handlers use the same declaration:

```ts
// app/features/orders/search.ts
import { recentSearches } from '#app/storage'

export function rememberSearch(term: string) {
  recentSearches.set((current) => [term, ...current.filter((t) => t !== term)].slice(0, 5))
}

rememberSearch('INV-1042')
rememberSearch('Grace')
recentSearches.get() // => ['Grace', 'INV-1042']
recentSearches.remove()
recentSearches.get() // => []
```

`get()` is synchronous and returns the same object for the same stored string, so you can call it in a render or a loop without parsing JSON each time. `set()` notifies every subscriber in this tab at once and the other tabs through the browser's `storage` event.

To react to changes without React, subscribe. The listener receives the new value and the call returns an unsubscribe function:

```ts
// app/features/layout/body-class.ts
import { sidebar } from '#app/storage'

const stop = sidebar.subscribe((value) => {
  document.body.classList.toggle('sidebar-collapsed', value.collapsed)
})

// later, when the layout unmounts
stop()
```

## Choose local or session storage

`area` picks where the value lives. `local`, the default, keeps a value until the user or your code clears it. `session` keeps it for the current tab only: closing the tab forgets it, and a second tab starts empty.

```ts
// app/storage.ts
import { defineStorage } from 'kitr/storage'

// Survives restarts: a preference.
export const ordersPageSize = defineStorage('orders-page-size', { default: 25 })

// Forgotten when the tab closes: the search history of this session.
export const recentSearches = defineStorage<string[]>('recent-searches', {
  default: [],
  area: 'session',
  version: 1,
})
```

`ordersPageSize.area` is `'local'` and `recentSearches.area` is `'session'`. On desktop and mobile, `session` items live in memory and are gone when the app restarts, which matches what a tab does in the browser.

## Validate stored values with a schema

Anything in storage can be edited by the user, an old version of your app or a browser extension. Pass a [Standard Schema](https://standardschema.dev) such as [zod](https://zod.dev) or [valibot](https://valibot.dev) and every read is checked. A value that fails the schema reads as the default:

```ts
// app/storage.ts
import { defineStorage } from 'kitr/storage'
import { z } from 'zod'

const orderFilters = z.object({
  status: z.enum(['open', 'paid', 'shipped']).nullable(),
  customer: z.string().max(80),
})

export const savedFilters = defineStorage('order-filters', {
  default: { status: null, customer: '' } as z.infer<typeof orderFilters>,
  schema: orderFilters,
})
```

```ts
// What happens with a tampered value
localStorage.setItem('acme:order-filters', '{"v":1,"d":{"status":"lost","customer":"Ada"}}')
savedFilters.get() // => { status: null, customer: '' }
```

The schema runs on reads, not on writes, so TypeScript guards what you write and the schema guards what comes back. The schema must be synchronous. An async schema, such as zod with an async `refine`, makes every read return the default.

## Change a value's shape with versions

When you change the shape of a stored value, old browsers still hold the old shape. Bump `version` and give `migrate` a function that converts what it finds. It receives the old data and the version it was saved under:

```ts
// app/storage.ts
import { defineStorage } from 'kitr/storage'

// Version 1 stored { collapsed: boolean }. Version 2 also remembers the width.
export const sidebar = defineStorage('sidebar', {
  default: { collapsed: false, width: 280 },
  version: 2,
  migrate: (old, fromVersion) => {
    if (fromVersion === 1) return { ...(old as { collapsed: boolean }), width: 280 }
    return { collapsed: false, width: 280 }
  },
})
```

```ts
// Ada's browser still holds a version 1 value
localStorage.getItem('acme:sidebar') // => '{"v":1,"d":{"collapsed":true}}'
sidebar.get() // => { collapsed: true, width: 280 }
```

The migrated value is returned but not written back until the next `set()`. If `migrate` throws, or there is no `migrate`, a value with another version reads as the default. When both `migrate` and `schema` are set, the schema checks the migrated value.

Don't change the shape of `default` without bumping `version`. The old values would still be read as the new type, and code that reads `sidebar.get().width` would get `undefined`.

## Expire a value after a time

`ttl` keeps a value for that many milliseconds after each `set()`, then treats it as missing. Use it for things that go stale, such as a dismissed notice that should come back next week:

```ts
// app/storage.ts
import { defineStorage } from 'kitr/storage'

const sevenDays = 7 * 24 * 60 * 60 * 1000

export const invoiceTipDismissed = defineStorage('invoice-tip-dismissed', {
  default: false,
  ttl: sevenDays,
})
```

```ts
invoiceTipDismissed.set(true)
localStorage.getItem('acme:invoice-tip-dismissed')
// => '{"v":1,"d":true,"e":1731542400000}'
invoiceTipDismissed.get() // => true, until seven days from now; then false
```

The expiry `e` is stored beside the value, so it holds across reloads. Every `set()` starts a new period. An expired value stays in storage until the next `set()` or `remove()`; it is never returned.

## Keep tabs in sync

When Ada collapses the sidebar in one tab, every other tab of `app.acme.com` updates too. `useStorage` subscribes to the browser's [`storage` event](https://developer.mozilla.org/en-US/docs/Web/API/Window/storage_event), which fires in the other tabs on every write to `localStorage`. You don't add anything for this; it works for every `local` item.

```tsx
// app/components/sidebar.tsx
import { useStorage } from 'kitr/storage/react'
import type { ReactNode } from 'react'
import { sidebar } from '#app/storage'

export function Sidebar({ children }: { children: ReactNode }) {
  const [{ collapsed }] = useStorage(sidebar)
  return <aside className={collapsed ? 'w-14' : 'w-72'}>{children}</aside>
}
```

`session` items don't sync, because each tab has its own session storage. On desktop and mobile the native drivers have no other tabs to hear from, so changes apply in the one window.

## Render on the server without a hydration mismatch

On the server there is no `localStorage`. `get()` returns the default and `set()` does nothing, so the same module imports safely on both sides. `useStorage` renders the default on the server **and** on the first browser render, then switches to the stored value right after hydration:

```tsx
// app/routes/orders.tsx
import { createFileRoute } from '@tanstack/react-router'
import { useStorage } from 'kitr/storage/react'
import { ordersPageSize } from '#app/storage'

export const Route = createFileRoute('/orders')({
  component: OrdersPage,
})

function OrdersPage() {
  const [pageSize, setPageSize] = useStorage(ordersPageSize)
  return (
    <select value={pageSize} onChange={(e) => setPageSize(Number(e.target.value))}>
      <option value={25}>25 per page</option>
      <option value={50}>50 per page</option>
      <option value={100}>100 per page</option>
    </select>
  )
}
```

If Ada saved 50, the server sends HTML with 25 selected, the browser hydrates with 25, and then shows 50. The markup always matches, so React never throws a hydration error.

Don't read `ordersPageSize.get()` directly in a server-rendered component: the server returns 25 and the browser returns 50, and React reports a mismatch. Use the hook. If the first HTML must already show the saved value, store it in a cookie instead, as the next sections show.

## Handle missing, invalid and blocked storage

Storage items never throw on a read. Each case below returns the default:

| Situation | `get()` returns | `set()` does |
| --- | --- | --- |
| Nothing saved yet | the default | saves the value |
| Saved value isn't valid JSON | the default | overwrites it |
| Saved value fails `schema` | the default | saves the value |
| Saved under another `version`, no `migrate` | the default | saves with the new version |
| Older than its `ttl` | the default | saves with a new expiry |
| On the server | the default | nothing |
| Storage blocked (some private modes, sandboxed iframes) | the default | nothing |
| Storage full | see below | doesn't throw |

When the browser refuses a write because storage is full, `set()` catches the error and still notifies subscribers. If the key had no saved value before, `get()` returns the new value for the rest of the page's life. If it had one, `get()` keeps returning the last value that was saved.

## Declare a cookie

A cookie is the one value both the browser and the server can read, so it is the right home for anything the server needs to render the first page, such as Ada's language. Declare it with `defineCookie`, next to the storage items:

```ts
// app/storage.ts
import { defineCookie } from 'kitr/storage'

export type Locale = 'en' | 'de' | 'fr'

export const localeCookie = defineCookie<Locale>('locale', {
  default: 'en',
  maxAge: 60 * 60 * 24 * 365,
})

export const tablePrefs = defineCookie('table-prefs', {
  default: { dense: false, columns: ['id', 'customer', 'total'] },
  maxAge: 60 * 60 * 24 * 30,
})
```

A cookie with a string default is stored as plain text: `acme:locale=de`. Any other default is stored as URL-encoded JSON: `acme:table-prefs=%7B%22dense%22%3Atrue%2C...`. Pass `codec` to choose yourself. `schema` works the same as on storage items.

Every `CookieOptions` field can be set on the item: `path`, `domain`, `maxAge`, `expires`, `secure`, `httpOnly` and `sameSite`. The item's options win over `cookie` in `config/storage.ts`.

Keep cookies small. The browser sends every cookie with every request to `app.acme.com`, and most browsers cap one cookie at about 4 KB. Large or private values belong in storage items or on the server.

## Read and write cookies in a component

In a component, `useCookie` works like `useStorage`:

```tsx
// app/components/locale-switch.tsx
import { useCookie } from 'kitr/storage/react'
import { type Locale, localeCookie } from '#app/storage'

export function LocaleSwitch() {
  const [locale, setLocale] = useCookie(localeCookie)
  return (
    <select value={locale} onChange={(e) => setLocale(e.target.value as Locale)}>
      <option value="en">English</option>
      <option value="de">Deutsch</option>
      <option value="fr">Français</option>
    </select>
  )
}
```

Ada picks Deutsch. The browser now holds:

```text
acme:locale=de; Max-Age=31536000; Path=/; SameSite=Lax
```

The next request to the server carries `Cookie: acme:locale=de`. Outside React, call the same methods on the item:

```ts
// app/features/settings/locale.ts
import { localeCookie } from '#app/storage'

localeCookie.set('fr')
localeCookie.get() // => 'fr'
localeCookie.remove()
localeCookie.get() // => 'en'
```

In the browser, `get()` with no argument reads `document.cookie`. `set()` always writes a script-readable cookie, even if the item says `httpOnly: true`, because the browser refuses to let scripts write `httpOnly` cookies. Cookies don't fire events across tabs; another tab sees the new value on its next read or render.

If other code writes `document.cookie`, for example a consent banner from a vendor, call `notifyCookiesChanged()` so mounted `useCookie` hooks re-read:

```ts
// app/lib/vendor-banner.ts
import { notifyCookiesChanged } from 'kitr/storage'

window.addEventListener('vendor:consent-saved', () => notifyCookiesChanged())
```

## Render cookies during server rendering

During server rendering there is no `document.cookie`, so `useCookie` needs the request's `Cookie` header. Wrap the tree once in `<CookieHeader>` in the root route. In a [TanStack Start](https://tanstack.com/start/latest) app, read the header in a server function and pass it down from the loader:

```tsx
// app/routes/__root.tsx
import { createRootRoute, Outlet } from '@tanstack/react-router'
import { createServerFn } from '@tanstack/react-start'
import { getRequest } from '@tanstack/react-start/server'
import { CookieHeader } from 'kitr/storage/react'

const readCookieHeader = createServerFn({ method: 'GET' }).handler(() =>
  getRequest().headers.get('cookie'),
)

export const Route = createRootRoute({
  loader: () => readCookieHeader(),
  component: RootComponent,
})

function RootComponent() {
  const cookieHeader = Route.useLoaderData()
  return (
    <CookieHeader value={cookieHeader}>
      <Outlet />
    </CookieHeader>
  )
}
```

With the wrapper, `<LocaleSwitch />` renders `Deutsch` in the first HTML for Ada, and the browser hydrates with the same value. Without it, the server renders the default (`English`) and the browser corrects it after hydration, which shows as a flash.

When you only need one cookie's value in a loader, skip the wrapper and read it from the headers directly. `get()` accepts a `Headers` object, a raw `Cookie` header string, or anything with a `cookie` field:

```ts
// app/routes/orders.tsx
import { createServerFn } from '@tanstack/react-start'
import { getRequest } from '@tanstack/react-start/server'
import { localeCookie } from '#app/storage'

export const readLocale = createServerFn({ method: 'GET' }).handler(() =>
  localeCookie.get(getRequest().headers),
)

localeCookie.get('acme:locale=de; acme:table-prefs=%7B%7D') // => 'de'
localeCookie.get(null) // => 'en'
```

## Read and set cookies on the server

On the server, `cookies()` from `kitr/storage/server` gives typed access to one request's cookies. Pass it the h3 event in a controller or middleware. Reads come from the request's `Cookie` header; writes append a `Set-Cookie` header to the response:

```ts
// server/controllers/settings_controller.ts
import type { HttpContext } from 'kitr/api'
import { cookies } from 'kitr/storage/server'
import { type Locale, localeCookie } from '#app/storage'

export default class SettingsController {
  async show({ event }: HttpContext) {
    const jar = cookies(event)
    return { locale: jar.get(localeCookie) }
  }

  async update({ event, body }: HttpContext<{}, {}, { locale: Locale }>) {
    const jar = cookies(event)
    jar.set(localeCookie, body.locale)
    return { locale: body.locale }
  }
}
```

`PUT /api/settings` with `{ "locale": "de" }` answers with this header:

```http
Set-Cookie: acme:locale=de; Max-Age=31536000; Path=/; SameSite=Lax
```

`jar.remove(item)` appends a header that expires the cookie (`Max-Age=0` and an `Expires` date in 1970). `jar.header` is the raw `Cookie` header, which you can pass to `<CookieHeader>`.

Where you only have Fetch primitives, such as a Cloudflare Worker or a plain `fetch` handler, pass the `Request` and the response `Headers`:

```ts
// server/edge/locale.ts
import { cookies } from 'kitr/storage/server'
import { localeCookie } from '#app/storage'

export function handleLocale(request: Request): Response {
  const headers = new Headers({ 'content-type': 'application/json' })
  const jar = cookies(request, headers)
  const locale = jar.get(localeCookie)
  if (locale === 'en') jar.set(localeCookie, 'de')
  return new Response(JSON.stringify({ locale }), { headers })
}
```

## Set an httpOnly cookie from the server

A cookie the browser's scripts must never read, such as an opaque session id, is `httpOnly` and is set only by the server. Declare it with `httpOnly: true`; the server write honours it:

```ts
// server/auth/session-cookie.ts
import { defineCookie } from 'kitr/storage'

export const sessionCookie = defineCookie('sid', {
  default: '',
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
  maxAge: 60 * 60 * 8,
})
```

```ts
// server/controllers/sessions_controller.ts
import type { HttpContext } from 'kitr/api'
import { cookies } from 'kitr/storage/server'
import { sessionCookie } from '#server/auth/session-cookie'

export default class SessionsController {
  async store({ event }: HttpContext) {
    const sessionId = crypto.randomUUID()
    cookies(event).set(sessionCookie, sessionId)
    return { ok: true }
  }

  async destroy({ event }: HttpContext) {
    cookies(event).remove(sessionCookie)
    return { ok: true }
  }
}
```

```http
Set-Cookie: acme:sid=3f2b...; Max-Age=28800; Path=/; Secure; HttpOnly; SameSite=Strict
```

Options passed to `set()` win over the item's, so `jar.set(sessionCookie, id, { maxAge: 60 * 60 * 24 * 30 })` writes a "remember me" cookie from the same declaration.

> **Warning**
> A cookie value is not signed or encrypted. Anyone can edit their own cookies, so never trust a cookie as proof of who someone is: store a random id and look it up on the server. For sign-in, use [Auth](/packages/auth).

## Share cookies across subdomains

To read one cookie on `acme.com`, `app.acme.com` and `billing.acme.com`, set `domain` to the parent domain. Set it once in config so every cookie gets it, or on one item:

```ts
// config/storage.ts
import { defineConfig } from 'kitr/storage'

export default defineConfig({
  prefix: 'acme:',
  cookie: {
    path: '/',
    domain: '.acme.com',
    sameSite: 'lax',
    secure: import.meta.env?.PROD ?? false,
  },
})
```

Every `Set-Cookie` now ends with `Domain=.acme.com; Path=/; ...`. A cookie set with one `domain` can only be removed with the same `domain`, so keep it in config rather than passing it to some `set()` calls and not others.

## Build and parse cookie headers by hand

`parseCookies` and `serializeCookie` are the two functions every cookie item uses. Use them when you need a cookie that isn't declared, such as one a third party set:

```ts
// server/lib/referrer.ts
import { parseCookies, serializeCookie } from 'kitr/storage'

parseCookies('acme:locale=de; utm_source=newsletter; broken')
// => { 'acme:locale': 'de', utm_source: 'newsletter' }

serializeCookie('utm_source', 'newsletter', { maxAge: 3600 })
// => 'utm_source=newsletter; Max-Age=3600; Path=/; SameSite=Lax'

serializeCookie('utm_source', null)
// => 'utm_source=; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Path=/; SameSite=Lax'
```

`parseCookies` skips parts without `=`, trims spaces and URL-decodes values; a value that fails to decode is kept as it is. `serializeCookie` URL-encodes the value and adds `Path=/` and `SameSite=Lax` unless you pass others, plus the cookie defaults from config. It does not add the config `prefix`; only items do.

An item can do the same for its own value: `localeCookie.serialize('de')` returns the full `Set-Cookie` value with the prefix, and `localeCookie.decode('de')` turns one raw value into the typed value or the default.

## Keep a value for the whole server

`defineKv` stores a value on the server that every request shares: a maintenance banner, a counter, a cached lookup from a slow vendor API. It looks like a storage item, but every method is async:

```ts
// server/state/banner.ts
import { defineKv } from 'kitr/storage'

export const banner = defineKv('banner', { default: { text: '', level: 'info' as 'info' | 'warning' } })
```

```ts
// server/controllers/banner_controller.ts
import type { HttpContext } from 'kitr/api'
import { banner } from '#server/state/banner'

export default class BannerController {
  async show() {
    return banner.get()
  }

  async update({ body }: HttpContext<{}, {}, { text: string }>) {
    await banner.set({ text: body.text, level: 'warning' }, { ttl: 6 * 60 * 60 * 1000 })
    return banner.get()
  }
}
```

```ts
await banner.get() // => { text: '', level: 'info' }
await banner.set({ text: 'Maintenance at 22:00', level: 'warning' }, { ttl: 6 * 60 * 60 * 1000 })
await banner.get() // => { text: 'Maintenance at 22:00', level: 'warning' }
// six hours later
await banner.get() // => { text: '', level: 'info' }
```

`ttl` is in milliseconds. Set it on the item (`defineKv('rates', { default: {}, ttl: 60_000 })`) to apply it to every write, or on one `set()` to override it. `set()` also takes a function of the current value, which reads then writes; two requests doing that at the same moment can overwrite each other, so use your store's own atomic commands for counters that must be exact.

`schema` and `codec` work as they do on storage items, and the config `prefix` applies to kv keys too.

> **Warning**
> The default kv driver keeps values in the server's memory. They are lost on every restart and deploy, and each server process or serverless instance has its own copy. Set a `kv` driver in `config/storage.ts` before you rely on a value in production.

## Store values natively on desktop and mobile

Storage items use the platform's own store when a platform registers a driver, and Web Storage otherwise. You declare and read items the same way everywhere; only where the bytes go changes. The storage provider hydrates the native store before the first render, so `get()` stays synchronous and already holds the saved values.

| Where the app runs | Driver | Where `local` items are saved |
| --- | --- | --- |
| Browser | `web:local` | `localStorage` |
| Desktop, Electron | `electron:ipc` | `kitr-storage.json` in Electron's `userData` folder |
| Desktop, Tauri | `tauri:store` | `kitr.json` in the app data folder |
| Mobile, Capacitor | `capacitor:preferences` | Capacitor Preferences |
| Server, or storage blocked | none | nothing; items read their defaults |

The storage provider looks for a registered driver in its own `register()` step, so the platform's provider (`@kitr/desktop/provider` or `@kitr/mobile/provider`) must be listed before `@kitr/storage/provider` in `kitrrc.ts`. When it is listed after, items keep using Web Storage inside the native shell.

On native platforms `session` items use an in-memory driver. Writes to a native store happen in the background after the in-memory copy updates; a failed write is logged as `[kitr/storage] <driver>: <error>` and the in-memory value stays.

### Browser

There is nothing to set up. Without a platform driver, `local` items use `localStorage` and `session` items use `sessionStorage`. Read what's stored in the browser devtools under Application → Local Storage. See [MDN on Web Storage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API) for size limits, which are about 5 MB per origin.

### Desktop with Electron

[Desktop](/packages/desktop) with the Electron shell registers `electronStorageDriver()`, which sends every write to the main process over the `kitr:storage:load`, `kitr:storage:set` and `kitr:storage:remove` IPC channels. The main process must serve them, which the desktop scaffold's `main.ts` does with one call:

```ts
// platforms/app/main.ts
import { app, ipcMain } from 'electron'
import { handleKitrIpc } from 'kitr/desktop/electron-main'

app.whenReady().then(() => {
  handleKitrIpc(ipcMain, app)
  // ... create the window
})
```

Values land in `kitr-storage.json` in [`app.getPath('userData')`](https://www.electronjs.org/docs/latest/api/app#appgetpathname). Pass `{ storageFile }` as the third argument to choose another file. Electron is the recommended desktop shell for most apps, because it ships its own browser engine and behaves the same on every OS.

### Desktop with Tauri

Inside a [Tauri](https://v2.tauri.app) webview, the desktop provider registers `tauriStoreDriver()` on the [store plugin](https://v2.tauri.app/plugin/store/), which writes `kitr.json` in the app data folder. Install and enable the plugin in your Tauri project as its docs describe; nothing changes in your items.

### Mobile with Capacitor

[Mobile](/packages/mobile) registers `preferencesDriver()` on [Capacitor Preferences](https://capacitorjs.com/docs/apis/preferences). iOS and Android may clear a WebView's `localStorage` when the device is low on space; Preferences is kept in the app's own data, so saved values survive.

## Testing

Storage items are module-level values, so a test reads and writes them directly. In Vitest's default Node environment there is no `localStorage`; give the items an in-memory driver with `setStorageDriver(createMemoryStorageDriver())` and they behave as they do in the browser. Cookies need no setup: pass a `Request` and a `Headers` object to `cookies()`.

```ts
// app/storage.test.ts
import { createTestApp } from 'kitr/testing'
import {
  createMemoryStorageDriver,
  getStorageDriver,
  setStorageDriver,
  setStoragePrefix,
} from 'kitr/storage'
import storageProvider from 'kitr/storage/provider'
import { cookies } from 'kitr/storage/server'
import { afterEach, beforeEach, describe, expect, it } from 'vitest'
import { localeCookie, recentSearches, sidebar } from '#app/storage'

beforeEach(() => {
  setStorageDriver(createMemoryStorageDriver())
})

afterEach(() => {
  setStoragePrefix('')
})

describe('app/storage', () => {
  it('remembers the sidebar under the configured prefix', async () => {
    await createTestApp({
      providers: [storageProvider],
      config: { storage: { prefix: 'acme:' } },
    })

    expect(sidebar.get()).toEqual({ collapsed: false })
    sidebar.set((s) => ({ collapsed: !s.collapsed }))
    expect(sidebar.get()).toEqual({ collapsed: true })
    expect(getStorageDriver('local')?.get('acme:sidebar')).toBe('{"v":1,"d":{"collapsed":true}}')
  })

  it('keeps recent searches in the session area', () => {
    recentSearches.set(['INV-1042'])
    expect(recentSearches.get()).toEqual(['INV-1042'])
    expect(getStorageDriver('session')?.keys()).toEqual(['recent-searches'])
  })

  it('reads and sets the locale cookie on the server', () => {
    const request = new Request('https://app.acme.com/orders', {
      headers: { cookie: 'locale=de' },
    })
    const response = new Headers()
    const jar = cookies(request, response)

    expect(jar.get(localeCookie)).toBe('de')
    jar.set(localeCookie, 'fr')
    expect(response.get('set-cookie')).toBe('locale=fr; Max-Age=31536000; Path=/; SameSite=Lax')
  })
})
```

The prefix and cookie defaults are module state too. Reset them in `afterEach` with `setStoragePrefix('')` and `setCookieDefaults({})` when a test sets them through config, or later tests see `acme:` keys.

To test components and the cross-tab behaviour, run the file in a DOM environment with `// @vitest-environment happy-dom` on its first line. Items then use the real `localStorage` and `sessionStorage`; clear them between tests and render with [Testing Library](https://testing-library.com/docs/react-testing-library/intro):

```tsx
// app/components/sidebar-toggle.test.tsx
// @vitest-environment happy-dom
import { fireEvent, render, screen } from '@testing-library/react'
import { afterEach, expect, it } from 'vitest'
import { SidebarToggle } from '#app/components/sidebar-toggle'

afterEach(() => localStorage.clear())

it('collapses and remembers it', () => {
  render(<SidebarToggle />)
  fireEvent.click(screen.getByRole('button', { name: 'Collapse sidebar' }))
  expect(screen.getByRole('button', { name: 'Expand sidebar' })).toBeTruthy()
  expect(localStorage.getItem('sidebar')).toBe('{"v":1,"d":{"collapsed":true}}')
})
```

To check what the server renders before hydration, call `renderToString` from `react-dom/server`: a `useStorage` component renders the default, and a `useCookie` component inside `<CookieHeader value="locale=de">` renders `de`.

## Extend

Two interfaces plug into storage: `StorageDriver`, the synchronous store behind `defineStorage` items on a platform, and `KvDriver`, the async store behind `defineKv` on the server. Their full types are in the [API reference](/packages/storage/api).

### Write a storage driver

| Member | Description |
| --- | --- |
| `name` | Shown in the devtools log. |
| `hydrate()` | Optional. Load every key into memory before the first render. The provider awaits it in `boot()`. |
| `get(key)` | The raw string, or `null`. Must answer synchronously. |
| `set(key, raw)` | Store a raw string. |
| `remove(key)` | Delete one key. |
| `keys()` | Every stored key, for the devtools panel. |
| `subscribe(listener)` | Optional. Call `listener(key)` when something outside this window changed a key (`null` for all keys); return an unsubscribe function. |

Most native stores are async. `createAsyncStorageDriver` wraps one: `load` fills an in-memory cache at boot, and `write` and `erase` run in the background after each change, so reads stay synchronous. This driver keeps values in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) through the small [idb-keyval](https://github.com/jakearchibald/idb-keyval) library:

```ts
// app/providers/idb-storage.ts
import { defineProvider } from 'kitr/app'
import { createAsyncStorageDriver } from 'kitr/storage'
import { createStore, del, entries, set } from 'idb-keyval'

const store = createStore('acme', 'storage')

export const idbStorageDriver = createAsyncStorageDriver({
  name: 'idb:acme',
  load: async () => {
    const out: Record<string, string> = {}
    for (const [key, value] of await entries<string, string>(store)) out[key] = value
    return out
  },
  write: (key, raw) => set(key, raw, store),
  erase: (key) => del(key, store),
  onError: (error) => console.warn('[acme] could not save to IndexedDB', error),
})

export default defineProvider({
  name: 'idb-storage',
  register(app) {
    app.drivers.register('storage', idbStorageDriver, { platform: 'web' })
  },
})
```

Register it in `kitrrc.ts` **before** the storage provider, because the storage provider picks the driver up in its own `register()`:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'

export default defineKitrConfig({
  providers: [
    () => import('#app/providers/idb-storage'),
    () => import('@kitr/storage/provider'),
    // ...
  ],
  // ...
})
```

The driver with the highest `priority` wins when several are registered; platform drivers default to `10`. `session` items keep an in-memory driver. To replace both areas directly, for example in a test or a script, call `setStorageDriver(driver, { session: otherDriver })`.

### Write a kv driver

A `KvDriver` has async `get`, `set` and `remove` over strings; `set` receives `{ ttl }` in milliseconds, and `keys(prefix)` is optional. This one wraps [ioredis](https://github.com/redis/ioredis):

```ts
// server/lib/redis-kv.ts
import Redis from 'ioredis'
import type { KvDriver } from 'kitr/storage'

export function redisKv(url: string): KvDriver {
  const redis = new Redis(url)
  return {
    get: (key) => redis.get(key),
    async set(key, raw, options) {
      if (options?.ttl) await redis.set(key, raw, 'PX', options.ttl)
      else await redis.set(key, raw)
    },
    async remove(key) {
      await redis.del(key)
    },
    keys: (prefix = '') => redis.keys(`${prefix}*`),
  }
}
```

Set it as `kv` in config. Every `defineKv` item then reads and writes Redis, under the same `prefix`:

```ts
// config/storage.ts
import { defineConfig } from 'kitr/storage'
import { redisKv } from '#server/lib/redis-kv'

export default defineConfig({
  prefix: 'acme:',
  cookie: { path: '/', sameSite: 'lax', secure: import.meta.env?.PROD ?? false },
  kv: redisKv(process.env.REDIS_URL ?? 'redis://localhost:6379'),
})
```

The kv driver only runs on the server. Keep `config/storage.ts` free of server-only imports if the browser bundle loads it, or build the driver in a server-only provider and call `setKvDriver(redisKv(url))` from its `register()`.

## Devtools

With [Devtools](/packages/devtools) installed, the provider adds a **Storage** panel in development. It lists every key in local storage, session storage and `document.cookie`, with the stored value pretty-printed and a **remove** button per row. The badge counts local and session keys. Two actions, **Clear localStorage** and **Clear sessionStorage**, remove every key in that area, including keys other code wrote.

At boot the provider logs `driver: web:local` (or the native driver's name, or `none (server)`) to the Log panel under `storage`, and logs `<key> changed outside this context` when a driver reports a change from elsewhere. Write your own lines to the same channel with `logStorage(app, 'label', data)`.

## Next steps

- [API reference](/packages/storage/api)
- [Secure storage](/packages/secure-storage): tokens and secrets in the OS vault.
- [Offline](/packages/offline): keep loaded query data on the device.
- [Desktop](/packages/desktop) and [Mobile](/packages/mobile): the platforms that bring native drivers.
- [MDN: Using HTTP cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies)


# Tables API

Source: https://kitr.dev/packages/table/api

`kitr/table` re-exports everything from `@tanstack/react-table` v9 and adds the following.

## useUrlTableState

```ts
function useUrlTableState(options: {
  search: TableSearch
  setSearch: (patch: Partial<TableSearch>) => void
  defaultPageSize?: number // default 20
}): {
  state: { sorting; pagination; columnFilters }
  onSortingChange
  onPaginationChange
  onColumnFiltersChange
  manualSorting: true
  manualPagination: true
  manualFiltering: true
}
```

Spread the result into `useTable` or `<DataTable>`. Router-agnostic: any router that can read and patch search params works.

## TableSearch

```ts
interface TableSearch {
  page?: number                   // one-based
  size?: number
  sort?: string                   // "name,-createdAt"
  filter?: Record<string, string>
}
```

## parseTableSearch

```ts
function parseTableSearch(raw: Record<string, unknown>): TableSearch
```

For a route's `validateSearch`. Keeps positive integer pages, sizes up to 500, well-formed sort strings and string filters; drops everything else.

## parseSort and formatSort

```ts
parseSort('-name,createdAt') // [{ id: 'name', desc: true }, { id: 'createdAt', desc: false }]
formatSort([{ id: 'name', desc: true }]) // '-name'
```

## dataTableFeatures

```ts
const dataTableFeatures = tableFeatures({
  rowSortingFeature,
  rowPaginationFeature,
  columnFilteringFeature,
  columnVisibilityFeature,
})
```

The features `<DataTable>` and `useUrlTableState` assume. TanStack Table v9 only bundles the features you register. Add more with `tableFeatures({ ...dataTableFeatures, rowSelectionFeature })`.


# Tables

Source: https://kitr.dev/packages/table

Admin screens, dashboards and reports all need the same thing: a table people can sort, page through and filter. Grace sorts Acme's orders by total, filters to the open ones, goes to page 3, and sends Linus the link. `kitr/table` keeps those choices in the page's URL, so the view survives a reload, works with the back button, and opens the same for Linus.

It is [TanStack Table](https://tanstack.com/table/latest) v9, re-exported unchanged, so `useTable`, column definitions and every feature work as TanStack documents them. On top it adds `useUrlTableState()`, which binds sorting, pagination and column filters to search params; `parseTableSearch()`, which validates those params from an untrusted URL; and `dataTableFeatures`, the feature set kitr's `<DataTable>` component expects.

It runs in the browser, inside React. The URL helpers do not depend on a router, but the examples use [router](/packages/router), whose `validateSearch` and `navigate` they were made for. For a list of cards or a feed rather than rows and columns, you don't need a table package; render the array.

The examples on this page build Acme's orders screen at `app.acme.com/orders`: thousands of orders with a customer, a total, a status and the date they were placed, served one page at a time by `/api/orders`.

## Install

```sh
kitr add table
```

What `kitr add` does:

- Adds `@kitr/table` and `@tanstack/react-table` to `dependencies` and installs them. Pass `--no-install` to skip the install.
- Adds `'@kitr/table'` to `packages` in `kitrrc.ts`. It registers no provider.
- Adds a `## kitr: table` section to `AGENTS.md`: put `validateSearch: parseTableSearch` on the route, spread `useUrlTableState({ search, setSearch })` into `useTable` or the registry `<DataTable>`, and keep sorting and paging in the URL so views are shareable.

It writes no config file and no other files, adds no env variables or scripts, and asks no questions. Tables are a client package, so in a project without React `kitr add` skips it with a warning. The `app`, `fullstack`, `saas`, `desktop` and `mobile` kits include it, along with the `data-table` component.

The styled table component is separate, because it is yours to edit. Copy it in with:

```sh
kitr ui add data-table
```

That writes `app/components/ui/data-table.tsx`, plus the `button` and `icon` components it uses.

`kitr remove table` takes `'@kitr/table'` out of `kitrrc.ts`, removes both dependencies and the `AGENTS.md` section, then lists files under `app/` and `config/` that still import `kitr/table`. It leaves `data-table.tsx` in place.

## Configure

`kitr/table` has no config file. Each table is configured where you call `useUrlTableState`:

```tsx
// app/routes/orders/index.tsx
import { createFileRoute } from 'kitr/router'
import { parseTableSearch, useUrlTableState } from 'kitr/table'

export const Route = createFileRoute('/orders/')({
  validateSearch: parseTableSearch,
  component: OrdersPage,
})

function OrdersPage() {
  const search = Route.useSearch()
  const navigate = Route.useNavigate()
  const urlState = useUrlTableState({
    search,
    setSearch: (patch) => navigate({ search: (prev) => ({ ...prev, ...patch }) }),
    defaultPageSize: 25,
  })
  // ...
}
```

| Option | Default | Description |
| --- | --- | --- |
| `search` | required | The current table params, `{ page?, size?, sort?, filter? }`. Usually `Route.useSearch()`. |
| `setSearch` | required | Merges a patch into the URL. A key set to `undefined` is removed from it. |
| `defaultPageSize` | `20` | Rows per page when the URL has no `size`. A size equal to it is left out of the URL. |

`useUrlTableState` returns options to spread into `useTable` or `<DataTable>`:

| Returned | Value |
| --- | --- |
| `state` | `{ sorting, pagination, columnFilters }`, derived from `search`. |
| `onSortingChange`, `onPaginationChange`, `onColumnFiltersChange` | Write the change to the URL through `setSearch`. |
| `manualSorting`, `manualPagination`, `manualFiltering` | All `true`: the server sorts, pages and filters. See [Sort and page in the browser](#sort-and-page-in-the-browser) to turn them off. |

The `<DataTable>` component from `kitr ui add data-table` takes these props, plus any [TanStack table option](https://tanstack.com/table/latest/docs/api/core/table):

| Prop | Default | Description |
| --- | --- | --- |
| `columns` | required | Column definitions, typed `ColumnDef<DataTableFeatures, Order>[]`. |
| `data` | required | The rows to show: the current page when the server pages. |
| `rowCount` | none | Total rows across all pages, so the footer can say "Page 3 of 40" and disable Next on the last page. |
| `empty` | `'No results.'` | What the body shows when `data` is empty. |
| `className` | none | Classes for the outer wrapper. |

## Show your first sortable table

Three pieces: column definitions, a route that accepts table params, and the table bound to them. Start with the columns:

```tsx
// app/features/orders/columns.tsx
import type { ColumnDef, DataTableFeatures } from 'kitr/table'

export interface Order {
  id: string
  customer: string
  total: number
  status: 'open' | 'paid' | 'refunded'
  placedAt: string
}

export const columns: ColumnDef<DataTableFeatures, Order>[] = [
  { accessorKey: 'customer', header: 'Customer' },
  {
    accessorKey: 'total',
    header: 'Total',
    cell: ({ row }) => `€${row.original.total.toFixed(2)}`,
  },
  { accessorKey: 'status', header: 'Status', enableSorting: false },
  {
    accessorKey: 'placedAt',
    header: 'Placed',
    cell: ({ row }) => new Date(row.original.placedAt).toLocaleDateString('en-GB'),
  },
]
```

Then the page. `validateSearch: parseTableSearch` makes `page`, `size`, `sort` and `filter` typed search params; the loader fetches the matching page; `useUrlTableState` turns the params into table state:

```tsx
// app/routes/orders/index.tsx
import { useSuspenseQuery } from 'kitr/query'
import { createFileRoute } from 'kitr/router'
import { parseTableSearch, useUrlTableState } from 'kitr/table'
import { DataTable } from '#components/ui/data-table'
import { columns } from '#app/features/orders/columns'
import { ordersPageQuery } from '#app/features/orders/queries'

export const Route = createFileRoute('/orders/')({
  validateSearch: parseTableSearch,
  loaderDeps: ({ search }) => search,
  loader: ({ context, deps }) => context.queryClient.ensureQueryData(ordersPageQuery.options(deps)),
  component: OrdersPage,
})

function OrdersPage() {
  const search = Route.useSearch()
  const navigate = Route.useNavigate()
  const { data } = useSuspenseQuery(ordersPageQuery.options(search))

  const urlState = useUrlTableState({
    search,
    setSearch: (patch) => navigate({ search: (prev) => ({ ...prev, ...patch }) }),
  })

  return <DataTable columns={columns} data={data.rows} rowCount={data.total} {...urlState} />
}
```

Open `/orders` and click the Total header. The URL becomes `/orders?sort=-total`, the loader fetches that page, and the table shows the largest orders first. Reload, and it is still sorted. [Fetch one page from the server](#fetch-one-page-from-the-server) shows `ordersPageQuery` and the API behind it.

## Define columns

A column needs an id and a header. `accessorKey` reads a field of the row and doubles as the id; `cell` renders it; `id` names a column that reads no field, such as a row of buttons:

```tsx
// app/features/orders/columns.tsx
import type { ColumnDef, DataTableFeatures } from 'kitr/table'
import { Badge } from '#components/ui/badge'
import { Button } from '#components/ui/button'
import type { Order } from './types'

export const columns: ColumnDef<DataTableFeatures, Order>[] = [
  { accessorKey: 'customer', header: 'Customer' },
  {
    accessorKey: 'status',
    header: 'Status',
    enableSorting: false,
    cell: ({ row }) => (
      <Badge variant={row.original.status === 'paid' ? 'default' : 'secondary'}>
        {row.original.status}
      </Badge>
    ),
  },
  {
    id: 'actions',
    header: '',
    enableSorting: false,
    cell: ({ row }) => (
      <Button variant="ghost" size="sm" onClick={() => console.log('refund', row.original.id)}>
        Refund
      </Button>
    ),
  },
]
```

The column id is what appears in the URL: sorting the `customer` column writes `sort=customer`. Keep ids short and stable, because changing one breaks links people saved. `enableSorting: false` stops a header from being clickable; in `<DataTable>` it renders as plain text.

For a typed `getValue()` in each cell, use TanStack's column helper with the same feature set:

```tsx
// app/features/orders/columns.tsx
import { createColumnHelper, type DataTableFeatures } from 'kitr/table'
import type { Order } from './types'

const column = createColumnHelper<DataTableFeatures, Order>()

export const columns = [
  column.accessor('customer', { header: 'Customer' }),
  column.accessor('total', {
    header: 'Total',
    cell: (info) => `€${info.getValue().toFixed(2)}`,
  }),
]
```

Define columns outside the component, or in `useMemo`, so the table does not rebuild them on every render.

## Keep sorting, paging and filters in the URL

`useUrlTableState` reads the table's state from `search` and writes every change back through `setSearch`. The URL is the only copy of the state, so there is nothing to sync. What lands in the URL with TanStack Router's default search serialiser:

| Table state | URL | Notes |
| --- | --- | --- |
| Page 3 | `?page=3` | One-based, unlike TanStack's zero-based `pageIndex`. Page 1 is left out. |
| 50 rows per page | `?size=50` | The default size is left out. `parseTableSearch` accepts up to 500. |
| Total, largest first | `?sort=-total` | A leading `-` means descending. |
| Customer A to Z, then newest | `?sort=customer%2C-placedAt` | Comma-separated, in priority order. The comma is URL-encoded. |
| Status is open | `?filter=%7B%22status%22%3A%22open%22%7D` | `filter` is an object, which the router stores as JSON: `{"status":"open"}`. |

Some writes also reset the page, because page 4 of the old order is meaningless in the new one:

| Change | What `setSearch` receives |
| --- | --- |
| Click a header | `{ sort: '-total', page: undefined }` |
| Clear sorting | `{ sort: undefined, page: undefined }` |
| Set a filter | `{ filter: { status: 'open' }, page: undefined }` |
| Clear the last filter | `{ filter: undefined, page: undefined }` |
| Next page | `{ page: 2, size: undefined }` |
| Back to page 1 at the default size | `{ page: undefined, size: undefined }` |

Clicking a header cycles through the sort directions. A number column such as Total starts with largest first (`-total`, then `total`, then unsorted); a text column such as Customer starts with A to Z.

Don't keep a copy of the sort or page in `useState` next to the table. Two sources of truth drift apart, and the back button only restores one of them.

## Validate the URL

Anyone can edit a URL, so every search param is untrusted. `parseTableSearch` keeps what is valid and drops the rest without throwing:

```ts
// app/features/orders/search.ts
import { parseTableSearch } from 'kitr/table'

parseTableSearch({ page: '2', size: '50', sort: '-total,customer', filter: { status: 'open' } })
// => { page: 2, size: 50, sort: '-total,customer', filter: { status: 'open' } }

parseTableSearch({ page: '0', size: '9999', sort: 'total;drop table', filter: 'open' })
// => {}

parseTableSearch({ page: '1.5', filter: { status: 'open', total: 100 } })
// => { filter: { status: 'open' } }
```

| Param | Kept when |
| --- | --- |
| `page` | A whole number of 1 or more. |
| `size` | A whole number from 1 to 500. |
| `sort` | Comma-separated column ids of letters, digits, `_` and `.`, each optionally prefixed with `-`. |
| `filter` | An object; only its string values are kept. |

To add params of your own, such as a search box, call it inside your own `validateSearch` and add your fields beside it:

```tsx
// app/routes/orders/index.tsx
import { createFileRoute } from 'kitr/router'
import { parseTableSearch } from 'kitr/table'

export const Route = createFileRoute('/orders/')({
  validateSearch: (raw: Record<string, unknown>) => ({
    ...parseTableSearch(raw),
    q: typeof raw.q === 'string' && raw.q.length <= 100 ? raw.q : undefined,
  }),
  component: OrdersPage,
})

function OrdersPage() {
  const { q } = Route.useSearch()
  return <p>Searching for {q}</p>
}
```

The sort pattern allows dotted ids such as `customer.name`, so a column can sort by a nested field. Your API should still accept only the columns it knows; see the next section.

## Fetch one page from the server

`useUrlTableState` sets `manualSorting`, `manualPagination` and `manualFiltering`, because the usual table is bigger than one response. The server sorts, filters and slices; the table shows what came back. Turn the search into a request in the query:

```ts
// app/features/orders/queries.ts
import { defineQuery } from 'kitr/query'
import type { TableSearch } from 'kitr/table'
import type { Order } from './columns'

export interface OrdersPage {
  rows: Order[]
  total: number
}

export const ordersPageQuery = defineQuery<TableSearch, OrdersPage>({
  key: (search) => ['orders', 'page', search],
  fetch: async (search, { signal }) => {
    const params = new URLSearchParams()
    if (search.page) params.set('page', String(search.page))
    if (search.size) params.set('size', String(search.size))
    if (search.sort) params.set('sort', search.sort)
    for (const [column, value] of Object.entries(search.filter ?? {})) params.set(column, value)
    const res = await fetch(`/api/orders?${params}`, { signal })
    return (await res.json()) as OrdersPage
  },
})
```

The whole `search` object is in the key, so every view is cached on its own and the back button shows the previous page instantly. On the server, read the same params, allow only known columns, and return the page with the total:

```ts
// server/controllers/orders_controller.ts
import type { HttpContext } from 'kitr/api'
import { parseSort } from 'kitr/table'
import { type Order, orders } from '#server/orders/data'

const sorters = {
  customer: (a: Order, b: Order) => a.customer.localeCompare(b.customer),
  total: (a: Order, b: Order) => a.total - b.total,
  placedAt: (a: Order, b: Order) => a.placedAt.localeCompare(b.placedAt),
}

export default class OrdersController {
  async index({ query }: HttpContext<Record<string, string>, Record<string, string>>) {
    const page = Math.max(1, Number(query.page) || 1)
    const size = Math.min(500, Number(query.size) || 20)
    const sorting = parseSort(query.sort).filter((s) => s.id in sorters)

    const rows = query.status ? orders.filter((o) => o.status === query.status) : [...orders]
    rows.sort((a, b) => {
      for (const { id, desc } of sorting) {
        const result = sorters[id as keyof typeof sorters](a, b)
        if (result) return desc ? -result : result
      }
      return 0
    })
    return { rows: rows.slice((page - 1) * size, page * size), total: rows.length }
  }
}
```

`parseSort('-total,customer')` returns `[{ id: 'total', desc: true }, { id: 'customer', desc: false }]`, and `formatSort()` turns that back into the string. Use the same page size default on both sides, or pass `size` always. Only ids in `sorters` are used, so a hand-edited `?sort=password` sorts nothing. With a database, build the `ORDER BY` from such an allow-list, never from the raw string. `kitr/table` imports React, so in a server without React, split the string yourself.

Pass the total as `rowCount`. Without it, a manually paged table cannot know how many pages there are, and Next stays disabled.

## Filter by a column

A filter is a column id and a string value. Set it from any input with `column.setFilterValue()`; `useUrlTableState` writes it to the URL and resets to page 1. An empty string removes the filter:

```tsx
// app/features/orders/status-filter.tsx
import type { DataTableFeatures, ReactTable } from 'kitr/table'
import type { Order } from './columns'

export function StatusFilter({ table }: { table: ReactTable<DataTableFeatures, Order> }) {
  const column = table.getColumn('status')
  return (
    <select
      aria-label="Status"
      value={(column?.getFilterValue() as string | undefined) ?? ''}
      onChange={(event) => column?.setFilterValue(event.target.value)}
    >
      <option value="">All statuses</option>
      <option value="open">Open</option>
      <option value="paid">Paid</option>
      <option value="refunded">Refunded</option>
    </select>
  )
}
```

`<DataTable>` builds its table inside, so a filter outside it writes the URL instead. That is the same thing, because the URL is the state:

```tsx
// app/routes/orders/index.tsx
import { createFileRoute } from 'kitr/router'
import { parseTableSearch } from 'kitr/table'

export const Route = createFileRoute('/orders/')({
  validateSearch: parseTableSearch,
  component: OrdersToolbar,
})

function OrdersToolbar() {
  const search = Route.useSearch()
  const navigate = Route.useNavigate()
  return (
    <select
      aria-label="Status"
      value={search.filter?.status ?? ''}
      onChange={(event) => {
        const status = event.target.value
        const { status: _, ...rest } = search.filter ?? {}
        const filter = status ? { ...rest, status } : rest
        navigate({
          search: (prev) => ({
            ...prev,
            filter: Object.keys(filter).length ? filter : undefined,
            page: undefined,
          }),
        })
      }}
    >
      <option value="">All statuses</option>
      <option value="open">Open</option>
      <option value="paid">Paid</option>
    </select>
  )
}
```

Filter values are always strings in the URL. A number filter (`minTotal=100`) arrives as `'100'`; convert it on the server. For free-text search across columns, add your own `q` param as in [Validate the URL](#validate-the-url), rather than a filter on one column.

## Change the page size

`table.setPageSize()` writes `size` to the URL and keeps the first visible row on screen, which from page 1 means staying on page 1:

```tsx
// app/features/orders/page-size.tsx
import type { DataTableFeatures, ReactTable } from 'kitr/table'
import type { Order } from './columns'

export function PageSize({ table }: { table: ReactTable<DataTableFeatures, Order> }) {
  return (
    <select
      aria-label="Rows per page"
      value={table.state.pagination.pageSize}
      onChange={(event) => table.setPageSize(Number(event.target.value))}
    >
      {[20, 50, 100].map((size) => (
        <option key={size} value={size}>
          {size} rows
        </option>
      ))}
    </select>
  )
}
// choosing 50 => setSearch({ page: undefined, size: 50 })
```

Choosing the default size again removes `size` from the URL. Sizes above 500 are dropped by `parseTableSearch` when the page loads, so a hand-edited `?size=100000` falls back to the default.

## Sort and page in the browser

For a small list that arrives in one response, such as the twenty orders of one customer, let the table sort, filter and page itself. Add TanStack's row models to the feature set, and turn the manual flags off after the spread:

```tsx
// app/features/orders/customer-orders.tsx
import {
  type ColumnDef,
  createFilteredRowModel,
  createPaginatedRowModel,
  createSortedRowModel,
  dataTableFeatures,
  filterFn_equalsString,
  sortFn_alphanumeric,
  sortFn_basic,
  type TableSearch,
  tableFeatures,
  useTable,
  useUrlTableState,
} from 'kitr/table'
import type { Order } from './columns'

const clientFeatures = tableFeatures({
  ...dataTableFeatures,
  sortedRowModel: createSortedRowModel(),
  paginatedRowModel: createPaginatedRowModel(),
  filteredRowModel: createFilteredRowModel(),
  sortFns: { alphanumeric: sortFn_alphanumeric, basic: sortFn_basic },
  filterFns: { equalsString: filterFn_equalsString },
})

const columns: ColumnDef<typeof clientFeatures, Order>[] = [
  { accessorKey: 'customer', header: 'Customer' },
  { accessorKey: 'total', header: 'Total' },
  { accessorKey: 'status', header: 'Status', filterFn: 'equalsString' },
]

export function CustomerOrders(props: {
  orders: Order[]
  search: TableSearch
  setSearch: (patch: Partial<TableSearch>) => void
}) {
  const urlState = useUrlTableState({ ...props, defaultPageSize: 10 })
  const table = useTable({
    features: clientFeatures,
    columns,
    data: props.orders,
    ...urlState,
    manualSorting: false,
    manualPagination: false,
    manualFiltering: false,
  })
  return <p>{table.getRowModel().rows.map((row) => row.original.customer).join(', ')}</p>
}
```

Given Grace's 120, Ada's 80 and Linus's 300 and `?sort=-total`, the rows come out Linus, Grace, Ada. The state still lives in the URL; only the work moved to the browser.

Turning the flags off is not enough on its own. `dataTableFeatures` has no row models, so without `sortedRowModel` and the rest the table keeps the rows in the order you passed them, whatever the URL says. TanStack v9 only ships the code for what you register, which is why kitr's default set is small.

## Hide columns

`dataTableFeatures` includes column visibility. Keep it in component state, or in [state](/packages/state) to remember it across visits, and merge it into the URL state:

```tsx
// app/features/orders/orders-table.tsx
import {
  type ColumnDef,
  type DataTableFeatures,
  dataTableFeatures,
  type TableSearch,
  useTable,
  useUrlTableState,
  type VisibilityState,
} from 'kitr/table'
import { useState } from 'react'
import type { Order } from './columns'

export function OrdersTable(props: {
  columns: ColumnDef<DataTableFeatures, Order>[]
  rows: Order[]
  search: TableSearch
  setSearch: (patch: Partial<TableSearch>) => void
}) {
  const urlState = useUrlTableState(props)
  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({ placedAt: false })
  const table = useTable({
    features: dataTableFeatures,
    columns: props.columns,
    data: props.rows,
    ...urlState,
    state: { ...urlState.state, columnVisibility },
    onColumnVisibilityChange: setColumnVisibility,
  })

  return (
    <fieldset>
      {table.getAllLeafColumns().map((column) => (
        <label key={column.id}>
          <input
            type="checkbox"
            checked={column.getIsVisible()}
            onChange={column.getToggleVisibilityHandler()}
          />
          {column.id}
        </label>
      ))}
    </fieldset>
  )
}
```

Spread `urlState` first and set `state` after it, merging `urlState.state` in. Writing `state: { columnVisibility }` alone would drop sorting, paging and filters. Visibility is a viewer's preference rather than part of the view, which is why it stays out of the URL.

## Select rows

Row selection is not in the default set, because many tables don't need it. Add `rowSelectionFeature` to a feature set of your own, and give rows a stable id so a selection survives a refetch:

```tsx
// app/features/orders/refund-table.tsx
import {
  type ColumnDef,
  dataTableFeatures,
  type RowSelectionState,
  rowSelectionFeature,
  tableFeatures,
  useTable,
} from 'kitr/table'
import { useState } from 'react'
import type { Order } from './columns'

const features = tableFeatures({ ...dataTableFeatures, rowSelectionFeature })

const columns: ColumnDef<typeof features, Order>[] = [{ accessorKey: 'customer', header: 'Customer' }]

export function RefundTable({ orders }: { orders: Order[] }) {
  const [rowSelection, setRowSelection] = useState<RowSelectionState>({})
  const table = useTable({
    features,
    columns,
    data: orders,
    getRowId: (order) => order.id,
    state: { rowSelection },
    onRowSelectionChange: setRowSelection,
  })

  return (
    <form>
      {table.getRowModel().rows.map((row) => (
        <label key={row.id}>
          <input
            type="checkbox"
            checked={row.getIsSelected()}
            onChange={row.getToggleSelectedHandler()}
          />
          {row.original.customer}
        </label>
      ))}
      <button type="submit" disabled={!table.getSelectedRowModel().rows.length}>
        Refund {table.getSelectedRowModel().rows.length} orders
      </button>
    </form>
  )
}
```

Checking Grace's order 1001 sets `rowSelection` to `{ '1001': true }`. Without `getRowId`, rows are keyed by their index on the page, so a selection points at different orders after a sort. `<DataTable>` is typed for `dataTableFeatures`; for a table with extra features, edit your copy of `data-table.tsx` or render the rows yourself as below.

## Render your own markup

`<DataTable>` is one possible rendering. To build a different one, such as a table that turns into cards on phones, call `useTable` with `dataTableFeatures` and render headers and cells with `table.FlexRender`:

```tsx
// app/features/orders/orders-grid.tsx
import {
  type ColumnDef,
  type DataTableFeatures,
  dataTableFeatures,
  type TableSearch,
  useTable,
  useUrlTableState,
} from 'kitr/table'
import type { Order } from './columns'

export function OrdersGrid(props: {
  columns: ColumnDef<DataTableFeatures, Order>[]
  rows: Order[]
  total: number
  search: TableSearch
  setSearch: (patch: Partial<TableSearch>) => void
}) {
  const table = useTable({
    features: dataTableFeatures,
    columns: props.columns,
    data: props.rows,
    rowCount: props.total,
    ...useUrlTableState(props),
  })

  return (
    <table>
      <thead>
        {table.getHeaderGroups().map((group) => (
          <tr key={group.id}>
            {group.headers.map((header) => (
              <th key={header.id} aria-sort={header.column.getIsSorted() === 'desc' ? 'descending' : header.column.getIsSorted() === 'asc' ? 'ascending' : 'none'}>
                <button
                  type="button"
                  disabled={!header.column.getCanSort()}
                  onClick={header.column.getToggleSortingHandler()}
                >
                  <table.FlexRender header={header} />
                </button>
              </th>
            ))}
          </tr>
        ))}
      </thead>
      <tbody>
        {table.getRowModel().rows.map((row) => (
          <tr key={row.id}>
            {row.getVisibleCells().map((cell) => (
              <td key={cell.id}>
                <table.FlexRender cell={cell} />
              </td>
            ))}
          </tr>
        ))}
      </tbody>
      <tfoot>
        <tr>
          <td>
            Page {table.state.pagination.pageIndex + 1} of {table.getPageCount()}
            <button type="button" disabled={!table.getCanNextPage()} onClick={() => table.nextPage()}>
              Next
            </button>
          </td>
        </tr>
      </tfoot>
    </table>
  )
}
```

With 45 orders and the default size of 20, `table.getPageCount()` is `3`. `aria-sort` on the header tells screen readers which way the column is sorted. [TanStack's table guides](https://tanstack.com/table/latest/docs/guide/tables) cover header groups, footers, pinning and the rest.

## Keep table state out of the URL

`useUrlTableState` only needs `search` and `setSearch`, so any state store works. For a table inside a dialog, where the URL should not change, keep the params in `useState`:

```tsx
// app/features/orders/pick-order-dialog.tsx
import { type ColumnDef, type DataTableFeatures, type TableSearch, useUrlTableState } from 'kitr/table'
import { useState } from 'react'
import { DataTable } from '#components/ui/data-table'
import type { Order } from './columns'

export function PickOrderDialog(props: { columns: ColumnDef<DataTableFeatures, Order>[]; orders: Order[] }) {
  const [search, setSearchState] = useState<TableSearch>({})
  const urlState = useUrlTableState({
    search,
    setSearch: (patch) => setSearchState((prev) => ({ ...prev, ...patch })),
    defaultPageSize: 10,
  })
  return <DataTable columns={props.columns} data={props.orders} {...urlState} />
}
```

Closing the dialog forgets the sort. Everything else, including the page resets and the defaults left out, behaves as it does in the URL.

## Testing

The table's state lives in `search` and leaves through `setSearch`, so a test renders the table with a `search` object and a mock `setSearch`, clicks, and asserts what would have gone into the URL. No router is needed:

```tsx
// app/features/orders/orders-grid.test.tsx
import { fireEvent, render, screen } from '@testing-library/react'
import {
  type ColumnDef,
  type DataTableFeatures,
  dataTableFeatures,
  type TableSearch,
  useTable,
  useUrlTableState,
} from 'kitr/table'
import { describe, expect, it, vi } from 'vitest'

interface Order {
  id: string
  customer: string
  total: number
  status: string
}

const orders: Order[] = [
  { id: '1001', customer: 'Grace', total: 120, status: 'open' },
  { id: '1002', customer: 'Ada', total: 80, status: 'paid' },
]

const columns: ColumnDef<DataTableFeatures, Order>[] = [
  { accessorKey: 'customer', header: 'Customer' },
  { accessorKey: 'total', header: 'Total' },
  { accessorKey: 'status', header: 'Status', enableSorting: false },
]

function OrdersGrid(props: { search: TableSearch; setSearch: (patch: Partial<TableSearch>) => void }) {
  const table = useTable({
    features: dataTableFeatures,
    columns,
    data: orders,
    rowCount: 45,
    ...useUrlTableState(props),
  })
  return (
    <div>
      {table.getHeaderGroups()[0]?.headers.map((header) => (
        <button
          key={header.id}
          type="button"
          disabled={!header.column.getCanSort()}
          onClick={header.column.getToggleSortingHandler()}
        >
          <table.FlexRender header={header} />
        </button>
      ))}
      <button type="button" onClick={() => table.nextPage()}>
        Next
      </button>
      <p>
        Page {table.state.pagination.pageIndex + 1} of {table.getPageCount()}
      </p>
    </div>
  )
}

describe('orders grid', () => {
  it('reads the page from the URL', () => {
    render(<OrdersGrid search={{ page: 2 }} setSearch={vi.fn()} />)
    expect(screen.getByText('Page 2 of 3')).toBeTruthy()
  })

  it('sorts by total, largest first, and resets the page', () => {
    const setSearch = vi.fn()
    render(<OrdersGrid search={{ page: 2 }} setSearch={setSearch} />)

    fireEvent.click(screen.getByRole('button', { name: 'Total' }))

    expect(setSearch).toHaveBeenLastCalledWith({ sort: '-total', page: undefined })
  })

  it('writes the next page to the URL', () => {
    const setSearch = vi.fn()
    render(<OrdersGrid search={{}} setSearch={setSearch} />)

    fireEvent.click(screen.getByRole('button', { name: 'Next' }))

    expect(setSearch).toHaveBeenLastCalledWith({ page: 2, size: undefined })
  })

  it('does not sort by status', () => {
    render(<OrdersGrid search={{}} setSearch={vi.fn()} />)
    expect((screen.getByRole('button', { name: 'Status' }) as HTMLButtonElement).disabled).toBe(true)
  })
})
```

To test the route's own `validateSearch`, call `parseTableSearch` with the raw params a link could carry, as in [Validate the URL](#validate-the-url). To render the real page with its loader, see [testing](/packages/testing#render-a-whole-page).

## Next steps

- [API reference](/packages/table/api): every export of `kitr/table`.
- [TanStack Table docs](https://tanstack.com/table/latest): features, row models and column options, imported from `kitr/table`.
- [Router](/packages/router): `validateSearch`, `loaderDeps` and `navigate`, which the URL state uses.
- [Query](/packages/query): cache each page of rows by its search params.
- [Testing](/packages/testing): render tables inside your app's providers.


# Tailwind API

Source: https://kitr.dev/packages/tailwind/api

Every export of `kitr/tailwind`, `kitr/tailwind/vite`, read from the published type definitions. The [guide](/packages/tailwind) shows them in use.

## kitr/tailwind

Re-exports `clsx`, `tailwind-merge` unchanged, plus the following.

### cn

```ts
function cn(...inputs: ClassValue[]): string;
```

Join class names and drop the Tailwind classes a later one overrides: clsx plus tailwind-merge,
as in shadcn. Put a component's `className` prop last so callers can override its defaults.

### defineConfig

```ts
const defineConfig: <const C extends TailwindConfig>(config: C) => C;
```

Types `config/tailwind.ts` against `TailwindConfig` and returns the object unchanged.

### TailwindConfig

```ts
interface TailwindConfig {
  /** Entry stylesheet relative to the project root. Default `app/styles/app.css`. */
  entry?: string;
  /** Use kitr's preset (`@kitr/tailwind/preset.css`). Default true. */
  preset?: boolean;
}
```

Options of `config/tailwind.ts`. They record how the project's stylesheet is set up; the build reads the CSS itself.

## kitr/tailwind/vite

### kitrTailwind

```ts
function kitrTailwind(): Plugin[];
```

Tailwind v4 for kitr apps. Exactly `@tailwindcss/vite`, exposed here so
`kitr add tailwind` has one import to write and one version to manage.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Tailwind

Source: https://kitr.dev/packages/tailwind

Most React apps style with utility classes now, and most of them spend their first afternoon wiring Tailwind to the design system: which blue is "primary", what dark mode keys off, how a component lets callers override its padding. `kitr add tailwind` does that wiring. `bg-background`, `text-primary` and `rounded-md` use the same colours and radii as the rest of the app, dark mode follows the [theme](/packages/theme) toggle, and `cn()` merges class names so the last one wins.

It is [Tailwind CSS v4](https://tailwindcss.com/docs) and its Vite plugin, unchanged, plus a preset stylesheet that maps kitr's design tokens onto Tailwind's theme, and `cn()` built on [clsx](https://github.com/lukeed/clsx) and [tailwind-merge](https://github.com/dcastil/tailwind-merge). It runs at build time and in the browser; there is nothing to call on the server. If you prefer plain CSS or CSS Modules, skip this package and use the helpers in [theme](/packages/theme) instead.

The examples style one screen through the page: the orders list in Acme's dashboard at `app.acme.com`, with a status badge, an order card and a dark mode.

## Install

```sh
kitr add tailwind
```

What `kitr add` does:

- Adds [react](/packages/react) first if the project does not have it, because tailwind requires it.
- Installs `@kitr/tailwind`, `tailwindcss`, `@tailwindcss/vite`, `clsx`, `tailwind-merge` and `class-variance-authority`.
- Adds `@kitr/tailwind` to `packages` in `kitrrc.ts`. The `kitr()` Vite plugin sees it there and loads `@tailwindcss/vite`.
- Writes `config/tailwind.ts` (shown under [Configure](#configure)).
- Writes `app/styles/app.css`, the stylesheet Tailwind starts from.
- In `app/routes/__root.tsx`, replaces `import 'kitr/theme/styles.css'` with `import '#app/styles/app.css'`, or adds that import after the first import line when the file has neither.
- Adds a `## kitr: tailwind` section to `AGENTS.md`: utilities map to kitr tokens, merge classes with `cn()`, dark mode is `data-theme="dark"` on `<html>`.

It registers no provider, adds no env variables and asks no questions. Files that already exist are left alone. The `app` and `fullstack` kits include tailwind, and so do the preset kits built on them.

`kitr remove tailwind` takes `@kitr/tailwind` out of `kitrrc.ts`, uninstalls `@kitr/tailwind`, `tailwindcss`, `@tailwindcss/vite` and `tailwind-merge`, deletes `config/tailwind.ts` and removes the `AGENTS.md` section. It leaves `app/styles/app.css`, the import in `__root.tsx`, `clsx` and `class-variance-authority`, because your components may still use them.

## Configure

`kitr add` writes this file:

```ts
// config/tailwind.ts
import { defineConfig } from 'kitr/tailwind'

export default defineConfig({
  entry: 'app/styles/app.css',
  preset: true,
})
```

| Option | Default | Description |
| --- | --- | --- |
| `entry` | `'app/styles/app.css'` | The stylesheet Tailwind starts from, relative to the project root. |
| `preset` | `true` | Whether the app uses kitr's preset (`kitr/tailwind/preset.css`). |

These two options record how the project is set up; the build does not read them today. Tailwind v4 is configured in CSS, so what actually happens is decided by the stylesheet. To change the entry, import a different file from `__root.tsx`. To drop the preset, remove its `@import` line ([Use plain Tailwind colours](#use-plain-tailwind-colours)). `kitr doctor` warns when `config/tailwind.ts` is missing, so keep the file.

The stylesheet `kitr add` writes is the real configuration:

```css
/* app/styles/app.css */
@import 'tailwindcss';
@import 'kitr/tailwind/preset.css';
@import 'kitr/theme/styles.css';

@source '../';
```

- `@import 'tailwindcss'` loads Tailwind's base styles and utilities.
- `@import 'kitr/tailwind/preset.css'` maps kitr's tokens onto Tailwind's theme, makes `dark:` follow `data-theme="dark"` and sets the page's base colours and font.
- `@import 'kitr/theme/styles.css'` defines the token values as `--kitr-*` CSS variables, for light and dark.
- `@source '../'` tells Tailwind to scan `app/` (one folder up from `app/styles/`) for class names.

The Vite side is one option on the `kitr()` plugin in `vite.config.ts`:

| Option | Default | Description |
| --- | --- | --- |
| `tailwind` | `true` when `@kitr/tailwind` is in `kitrrc.ts` | Load `@tailwindcss/vite`. Set `false` to leave it out, as the generated `vitest.config.ts` does. |

There are no env variables. There is no `tailwind.config.js` either: Tailwind v4 reads its theme from CSS.

## Style your first component

On the server and in the browser, class names are plain strings, so a styled component is a component with `className`. Here is the badge for an order's status:

```tsx
// app/features/orders/order-status-badge.tsx
export function OrderStatusBadge({ status }: { status: 'paid' | 'pending' | 'refunded' }) {
  return (
    <span className="inline-flex items-center rounded-md border border-border bg-muted px-2 py-0.5 text-xs font-medium text-muted-foreground">
      {status}
    </span>
  )
}
```

Use it anywhere:

```tsx
// app/routes/orders/index.tsx
import { createFileRoute } from '@tanstack/react-router'
import { OrderStatusBadge } from '#app/features/orders/order-status-badge'

export const Route = createFileRoute('/orders/')({
  component: () => (
    <main className="mx-auto max-w-3xl p-6">
      <h1 className="text-2xl font-semibold text-foreground">Orders</h1>
      <p className="mt-2 text-muted-foreground">
        Order ACME-1042 from Grace <OrderStatusBadge status="paid" />
      </p>
    </main>
  ),
})
```

Run `npm run dev` and open `/orders`. The heading uses the theme's foreground colour, the badge sits on the muted surface with the theme's border and radius. Switch the theme to dark and both follow without a `dark:` class, because the tokens change under them.

## Use the theme's colours

The preset maps every kitr token to a Tailwind theme variable. Each colour works with every colour utility (`bg-`, `text-`, `border-`, `ring-`, `fill-`, `outline-`...) and with opacity modifiers like `bg-primary/90`.

| Class | Token | Use it for |
| --- | --- | --- |
| `bg-background`, `text-foreground` | `--kitr-color-background`, `--kitr-color-foreground` | The page and its text. |
| `bg-muted`, `text-muted-foreground` | `--kitr-color-muted`, `--kitr-color-mutedForeground` | Quiet surfaces and secondary text. |
| `bg-primary`, `text-primary-foreground` | `--kitr-color-primary`, `--kitr-color-primaryForeground` | Main buttons and links. |
| `bg-destructive`, `text-destructive-foreground` | `--kitr-color-destructive`, `--kitr-color-destructiveForeground` | Delete buttons and errors. |
| `border-border` | `--kitr-color-border` | Borders and dividers. |
| `ring-ring` | `--kitr-color-ring` | Focus rings. |
| `rounded-sm`, `rounded-md`, `rounded-lg` | `--kitr-radius-sm`, `-md`, `-lg` | Corner radii (0.25, 0.5 and 0.75 rem by default). |
| `font-sans`, `font-mono` | `--kitr-font-sans`, `--kitr-font-mono` | The system font stacks. |
| `shadow-sm`, `shadow-md` | `--kitr-shadow-sm`, `--kitr-shadow-md` | Soft elevation. |

The preset also sets every element's default border colour to `border-border`, and gives `<body>` the background, text colour and sans font. A plain `border` class therefore draws a themed line.

```tsx
// app/features/orders/order-card.tsx
export function OrderCard({ number, customer, total }: { number: string; customer: string; total: string }) {
  return (
    <article className="rounded-lg border bg-background p-4 shadow-sm">
      <h2 className="font-mono text-sm text-muted-foreground">{number}</h2>
      <p className="mt-1 text-lg text-foreground">{customer}</p>
      <p className="mt-3 font-semibold text-primary">{total}</p>
      <button type="button" className="mt-4 rounded-md bg-destructive px-3 py-1.5 text-sm text-destructive-foreground hover:bg-destructive/90">
        Refund
      </button>
    </article>
  )
}
```

Tailwind's own palette (`bg-sky-500`, `text-zinc-600`) is still there. Use it for one-off colours such as chart series, and the theme classes for anything that should change with the theme.

## Change a colour

The token values live in CSS variables, so change one by setting the variable after the imports. Acme's primary colour is orange:

```css
/* app/styles/app.css */
@import 'tailwindcss';
@import 'kitr/tailwind/preset.css';
@import 'kitr/theme/styles.css';

@source '../';

:root {
  --kitr-color-primary: oklch(68% 0.19 45);
  --kitr-color-ring: oklch(68% 0.19 45);
  --kitr-radius-md: 0.375rem;
}

[data-theme="dark"] {
  --kitr-color-primary: oklch(75% 0.16 45);
  --kitr-color-ring: oklch(75% 0.16 45);
}
```

Every `bg-primary`, `text-primary` and `ring-ring` in the app, and every component from `kitr ui add`, turns orange. Set the dark values under `[data-theme="dark"]`, or the light ones are used in both themes.

Don't edit the values in `@theme` (`--color-primary`) to change a colour. The preset defines those as references to the `--kitr-*` variables, and replacing them breaks dark mode.

## Add your own colours and sizes

For a token kitr does not have, add it to Tailwind's theme with an `@theme` block. Each `--color-*` variable becomes a colour utility, `--text-*` a font size, and so on:

```css
/* app/styles/app.css */
@import 'tailwindcss';
@import 'kitr/tailwind/preset.css';
@import 'kitr/theme/styles.css';

@source '../';

@theme {
  --color-success: oklch(62% 0.17 150);
  --color-success-foreground: oklch(99% 0 0);
  --text-display: 2.5rem;
}
```

```tsx
// app/features/orders/paid-banner.tsx
export function PaidBanner() {
  return (
    <div className="rounded-md bg-success p-3 text-success-foreground">
      <p className="text-display">Paid</p>
    </div>
  )
}
```

A colour that should differ in dark mode goes through a variable of your own, the way the preset does it:

```css
/* app/styles/app.css */
:root { --acme-success: oklch(62% 0.17 150); }
[data-theme="dark"] { --acme-success: oklch(72% 0.15 150); }

@theme inline {
  --color-success: var(--acme-success);
}
```

`@theme inline` makes the utility use the variable itself, so it changes when `data-theme` changes. The [Tailwind theme docs](https://tailwindcss.com/docs/theme) list every namespace.

## Support dark mode

The preset redefines the `dark:` variant to match `data-theme="dark"` on any ancestor, which is what `useTheme()` from [theme](/packages/theme) sets on `<html>`:

```css
/* from kitr/tailwind/preset.css */
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
```

Theme classes switch by themselves. Use `dark:` only for colours outside the theme:

```tsx
// app/features/orders/order-chart-legend.tsx
export function OrderChartLegend() {
  return (
    <ul className="flex gap-4 text-sm">
      <li className="text-sky-700 dark:text-sky-300">Online</li>
      <li className="text-amber-700 dark:text-amber-300">In store</li>
    </ul>
  )
}
```

A toggle button calls `useTheme()`:

```tsx
// app/components/theme-button.tsx
import { useTheme } from 'kitr/theme'

export function ThemeButton() {
  const { resolved, toggle } = useTheme()
  return (
    <button type="button" onClick={toggle} className="rounded-md border px-3 py-1.5 text-sm hover:bg-muted">
      {resolved === 'dark' ? 'Light mode' : 'Dark mode'}
    </button>
  )
}
```

Tailwind's default `dark:` follows the operating system's `prefers-color-scheme`. With the preset it follows the attribute instead, so the user's choice in the app wins. The theme's `'system'` setting still follows the operating system, by setting the attribute for you.

## Merge classes with cn()

`cn()` takes any mix of strings, objects, arrays and falsy values, joins them with clsx, then removes Tailwind classes that a later class overrides:

```ts
import { cn } from 'kitr/tailwind'

cn('rounded-md border p-4', 'p-8')
// => 'rounded-md border p-8'

cn('px-3 py-1', { 'opacity-50': true, hidden: false }, ['text-sm', undefined])
// => 'px-3 py-1 opacity-50 text-sm'

cn('bg-primary hover:bg-primary/90', 'bg-destructive')
// => 'hover:bg-primary/90 bg-destructive'

cn('text-sm text-muted-foreground', 'text-destructive')
// => 'text-sm text-destructive'
```

Without merging, `'p-4 p-8'` leaves both classes on the element and the one that wins depends on the order in Tailwind's stylesheet, not the order you wrote. tailwind-merge knows which classes conflict: `text-sm` (a size) and `text-destructive` (a colour) both stay, `px-2` followed by `p-4` leaves only `p-4`.

## Accept a className prop

Components take `className` and put it last in `cn()`, so callers can adjust them without a new prop for every change:

```tsx
// app/features/orders/order-card.tsx
import { cn } from 'kitr/tailwind'
import type { ComponentProps } from 'react'

export function OrderCard({ className, ...props }: ComponentProps<'article'>) {
  return <article className={cn('rounded-lg border bg-background p-4 shadow-sm', className)} {...props} />
}
```

```tsx
<OrderCard className="p-8 shadow-md" />
// renders class="rounded-lg border bg-background p-8 shadow-md"
```

Don't join with a template string (`` `p-4 ${className}` ``). Both padding classes reach the browser and the result depends on stylesheet order.

## Build variants with cva

A component with variants (a status, a size) maps each one to classes. [class-variance-authority](https://cva.style/docs) is installed by `kitr add tailwind`, and the components from `kitr ui add` use it:

```tsx
// app/features/orders/order-status-badge.tsx
import { cva, type VariantProps } from 'class-variance-authority'
import { cn } from 'kitr/tailwind'
import type { ReactNode } from 'react'

export const orderStatusBadge = cva('inline-flex items-center rounded-md px-2 py-0.5 text-xs font-medium', {
  variants: {
    status: {
      paid: 'bg-primary text-primary-foreground',
      pending: 'bg-muted text-muted-foreground',
      refunded: 'bg-destructive text-destructive-foreground',
    },
    size: {
      sm: 'text-xs',
      md: 'px-3 py-1 text-sm',
    },
  },
  defaultVariants: { status: 'pending', size: 'sm' },
})

type Props = VariantProps<typeof orderStatusBadge> & { className?: string; children: ReactNode }

export function OrderStatusBadge({ status, size, className, children }: Props) {
  return <span className={cn(orderStatusBadge({ status, size }), className)}>{children}</span>
}
```

```tsx
<OrderStatusBadge status="refunded" size="md">Refunded</OrderStatusBadge>
// class="inline-flex items-center rounded-md font-medium bg-destructive text-destructive-foreground px-3 py-1 text-sm"
```

`cn()` around the `cva` call is what lets `size: 'md'` replace the base `px-2 py-0.5 text-xs` instead of adding to it. `cva` is also re-exported from `kitr/theme`, if you would rather import it from there.

## Teach cn() about your own tokens

tailwind-merge only knows Tailwind's built-in scales. A custom font size such as `text-display` looks like a colour to it, so `cn('text-display', 'text-primary')` drops `text-display`. Build your own `cn` with `extendTailwindMerge` and list the new values:

```ts
// app/lib/cn.ts
import { clsx, type ClassValue } from 'clsx'
import { extendTailwindMerge } from 'tailwind-merge'

const merge = extendTailwindMerge({
  extend: { theme: { text: ['display'] } },
})

export function cn(...inputs: ClassValue[]) {
  return merge(clsx(inputs))
}

cn('text-display', 'text-primary')
// => 'text-display text-primary'
```

Custom colours need nothing: `cn('bg-success', 'bg-primary')` already returns `'bg-primary'`. `clsx` and `twMerge` are also exported from `kitr/tailwind`, for the cases where you want only one half of `cn()`.

## Tell Tailwind where your classes are

Tailwind generates only the classes it finds in your source files. `@source '../'` in `app/styles/app.css` points it at `app/`. Classes written anywhere else need their own line:

```css
/* app/styles/app.css */
@import 'tailwindcss';
@import 'kitr/tailwind/preset.css';
@import 'kitr/theme/styles.css';

@source '../';
@source '../../server/mail';
@source '../../node_modules/@acme/ui/dist';
```

Tailwind finds classes by reading the files as text, so a class has to appear whole:

```tsx
// Don't: Tailwind never sees "bg-primary" or "bg-destructive"
<span className={`bg-${order.paid ? 'primary' : 'destructive'}`} />

// Do: both full class names are in the source
<span className={order.paid ? 'bg-primary' : 'bg-destructive'} />
```

A class that is missing from the build shows up in the HTML but has no style. That is almost always a class built from pieces or a folder no `@source` covers.

## Style kitr's own components

Headless kitr components mark their parts with `data-kitr` attributes, so you can reach them with Tailwind's arbitrary variants. The field wrapper from [forms](/packages/forms) is one:

```tsx
// app/features/orders/refund-reason-field.tsx
import { FieldInput, FormField } from 'kitr/forms'

export function RefundReasonField() {
  return (
    <FormField
      name="reason"
      label="Reason for the refund"
      className="grid gap-1.5 [&_[data-kitr=label]]:text-sm [&_[data-kitr=label]]:font-medium [&_[data-kitr=field-error]]:text-sm [&_[data-kitr=field-error]]:text-destructive"
    >
      <FieldInput className="rounded-md border bg-background px-3 py-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring" />
    </FormField>
  )
}
```

For a finished look, `kitr ui add form` copies a styled version into `app/components/ui/form.tsx`. Every component `kitr ui add` copies is plain Tailwind on the theme classes and `cn()`, and the code is yours to change.

## Use plain Tailwind colours

To use Tailwind without kitr's tokens, remove the preset import, and the theme stylesheet if nothing else needs it:

```css
/* app/styles/app.css */
@import 'tailwindcss';

@source '../';
```

Then set `preset: false` in `config/tailwind.ts` so the file still describes the project. Without the preset, `bg-primary` and the other theme classes stop existing, `dark:` goes back to following `prefers-color-scheme`, and components from `kitr ui add` lose their colours.

## Wire Tailwind into a custom Vite config

The `kitr()` plugin loads `@tailwindcss/vite` for you. If you build a Vite config without `kitr()`, or want to control the plugin order, turn it off there and add `kitrTailwind()` from `kitr/tailwind/vite`. It returns exactly `@tailwindcss/vite`'s plugins:

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { kitr } from 'kitr/vite'
import { kitrTailwind } from 'kitr/tailwind/vite'

export default defineConfig({
  plugins: [kitrTailwind(), kitr({ tailwind: false })],
})
```

Don't add Tailwind's plugin while `kitr()` also loads it. The CSS is then processed twice.

## Fix styles that do not apply

Most Tailwind problems in a kitr app come from one of a few causes. Check them in this order:

| Symptom | Cause | Fix |
| --- | --- | --- |
| No Tailwind styles at all | `app/styles/app.css` is not imported, or `@kitr/tailwind` is missing from `packages` in `kitrrc.ts` so the Vite plugin is not loaded. | Import `#app/styles/app.css` in `app/routes/__root.tsx`; run `kitr doctor`. |
| `bg-primary` and other theme classes do nothing | The preset import is missing from `app/styles/app.css`. | Add `@import 'kitr/tailwind/preset.css';` after `@import 'tailwindcss';`. |
| Theme classes resolve but have no colour | `kitr/theme/styles.css` is not imported, so the `--kitr-*` variables are undefined. | Add `@import 'kitr/theme/styles.css';`. |
| `dark:` classes never apply | Nothing sets `data-theme="dark"` on `<html>`. | Mount the [theme](/packages/theme) provider and switch with `useTheme()`. |
| One class works in one file but not another | The file is outside every `@source` folder, or the class is built from pieces. | Add an `@source` line, or write the whole class name. |
| A caller's `className` does not win | The component joins classes with a template string. | Use `cn(base, className)`. |
| A custom class disappears when merged | tailwind-merge treats it as a conflicting class. | Extend it ([Teach cn() about your own tokens](#teach-cn-about-your-own-tokens)). |

`kitr doctor` checks the parts kitr owns: it warns when `config/tailwind.ts` is missing and when `vite.config.ts` does not use the `kitr()` plugin. In the browser's devtools, a class that appears on the element but has no matching rule in the Styles panel was not generated; one that has a rule crossed out was overridden.

## Testing

Tests do not build CSS. The `vitest.config.ts` that kitr writes runs `kitr({ react: true, tailwind: false })`, so a test checks which classes a component renders, not what they look like. Test `cn()` merges and variant classes directly:

```tsx
// app/features/orders/order-status-badge.test.tsx
import { render, screen } from '@testing-library/react'
import { cn } from 'kitr/tailwind'
import { describe, expect, it } from 'vitest'
import { OrderStatusBadge, orderStatusBadge } from './order-status-badge'

describe('OrderStatusBadge', () => {
  it('uses the theme colours for each status', () => {
    expect(orderStatusBadge({ status: 'paid' })).toContain('bg-primary text-primary-foreground')
    expect(orderStatusBadge()).toContain('bg-muted text-muted-foreground')
  })

  it('lets a size replace the base padding', () => {
    render(
      <OrderStatusBadge status="refunded" size="md">
        Refunded
      </OrderStatusBadge>,
    )
    const badge = screen.getByText('Refunded')
    expect(badge.className).toContain('px-3 py-1 text-sm')
    expect(badge.className).not.toContain('px-2')
  })

  it('lets callers override classes', () => {
    render(
      <OrderStatusBadge status="paid" className="rounded-lg">
        Paid
      </OrderStatusBadge>,
    )
    expect(screen.getByText('Paid').className.split(' ')).toContain('rounded-lg')
    expect(screen.getByText('Paid').className.split(' ')).not.toContain('rounded-md')
  })

  it('merges with cn the way the component does', () => {
    expect(cn('px-2 py-1', 'px-4')).toBe('py-1 px-4')
    expect(cn('text-sm', { 'text-lg': true }, false, undefined)).toBe('text-lg')
  })
})
```

To check how a page actually looks, light and dark, use a browser test with [Playwright](https://playwright.dev/docs/screenshots) against `npm run dev`.

## Next steps

- [API reference](/packages/tailwind/api): `cn`, `defineConfig`, `TailwindConfig` and `kitrTailwind`.
- [Tailwind CSS docs](https://tailwindcss.com/docs): every utility, variant and the `@theme` syntax.
- [Theme](/packages/theme): the tokens behind the classes, `useTheme()` and `kitr ui add`.
- [Forms](/packages/forms): headless fields you style with the `data-kitr` attributes.
- [Project structure](/docs/project-structure): where `app/styles/app.css` and `config/` sit.


# Testing API

Source: https://kitr.dev/packages/testing/api

Every export of `kitr/testing`, `kitr/testing/react`, read from the published type definitions. The [guide](/packages/testing) shows them in use.

## kitr/testing

### createApp

```ts
function createApp(options?: CreateAppOptions): KitrApp;
```

Creates the app object that owns the container, config and providers. Call `boot()` on it
before reading services; one app per client, per server process and per test.

### createTestApp

```ts
function createTestApp(options?: CreateAppOptions): Promise<KitrApp>;
```

Creates and boots an app for one test, with `environment: 'test'` and the providers and config
you pass. Use it to read services from the container or to render components with `renderWithKitr`.

### createTestClient

```ts
function createTestClient(target: {
  fetch(request: Request): Promise<Response>;
} | string, defaults?: {
  headers?: Record<string, string>;
}): {
  get: <T = unknown>(path: string, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
  post: <T = unknown>(path: string, body?: unknown, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
  put: <T = unknown>(path: string, body?: unknown, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
  patch: <T = unknown>(path: string, body?: unknown, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
  delete: <T = unknown>(path: string, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
};
```

Request helper for API tests against anything with `fetch(request)`: a kitr server, a Start
handler, or a real URL. It sends JSON, parses JSON back and adds `defaults.headers` to every call,
without opening a port when given a handler.

### TestResponse

```ts
interface TestResponse<T = unknown> {
  /** The HTTP status code, such as `201` or `422`. */
  status: number;
  /** The response headers. */
  headers: Headers;
  /** The body parsed as JSON; the raw text when it is not JSON; `undefined` when it is empty. */
  body: T;
  /** The raw `Response`. Its body has already been read. */
  response: Response;
}
```

What every `createTestClient` call resolves to: the status, headers and parsed body of one response.

## kitr/testing/react

### createApp

```ts
function createApp(options?: CreateAppOptions): KitrApp;
```

Creates the app object that owns the container, config and providers. Call `boot()` on it
before reading services; one app per client, per server process and per test.

### createTestApp

```ts
function createTestApp(options?: CreateAppOptions): Promise<KitrApp>;
```

Creates and boots an app for one test, with `environment: 'test'` and the providers and config
you pass. Use it to read services from the container or to render components with `renderWithKitr`.

### createTestClient

```ts
function createTestClient(target: {
  fetch(request: Request): Promise<Response>;
} | string, defaults?: {
  headers?: Record<string, string>;
}): {
  get: <T = unknown>(path: string, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
  post: <T = unknown>(path: string, body?: unknown, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
  put: <T = unknown>(path: string, body?: unknown, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
  patch: <T = unknown>(path: string, body?: unknown, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
  delete: <T = unknown>(path: string, init?: {
    headers?: Record<string, string>;
  }) => Promise<TestResponse<T>>;
};
```

Request helper for API tests against anything with `fetch(request)`: a kitr server, a Start
handler, or a real URL. It sends JSON, parses JSON back and adds `defaults.headers` to every call,
without opening a port when given a handler.

### renderWithKitr

```ts
function renderWithKitr(ui: ReactElement, { app, queryData, wrapper: Extra, ...options }: RenderWithKitrOptions): import("@testing-library/react").RenderResult<typeof import("@testing-library/dom/types/queries"), HTMLElement, HTMLElement>;
```

Render inside the same providers the app uses, with the query cache pre-seeded.
Pass a `wrapper` to add a router (e.g. `RouterProvider` with a memory history).

### RenderWithKitrOptions

```ts
interface RenderWithKitrOptions extends Omit<RenderOptions, 'wrapper'> {
  /** The booted app whose providers wrap the component, usually from `createTestApp`. */
  app: KitrApp;
  /** Seed the query cache: `[[['projects', 'detail', '1'], project]]`. Needs @kitr/query's provider. */
  queryData?: Array<[
    readonly unknown[],
    unknown
  ]>;
  /** An extra wrapper rendered inside the app's providers, such as a router with a memory history. */
  wrapper?: (props: {
    children: ReactNode;
  }) => ReactElement;
}
```

Options for `renderWithKitr`: Testing Library's render options plus the app, cache seed and an extra wrapper.

### TestResponse

```ts
interface TestResponse<T = unknown> {
  /** The HTTP status code, such as `201` or `422`. */
  status: number;
  /** The response headers. */
  headers: Headers;
  /** The body parsed as JSON; the raw text when it is not JSON; `undefined` when it is empty. */
  body: T;
  /** The raw `Response`. Its body has already been read. */
  response: Response;
}
```

What every `createTestClient` call resolves to: the status, headers and parsed body of one response.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Testing

Source: https://kitr.dev/packages/testing

The hard part of testing an app is rarely the assertion. It is the setup: the providers a component expects, the query cache, the router, a server listening on a port. `kitr/testing` boots your real app for each test, renders components inside its providers, and sends requests to your API by calling its fetch handler directly, so no server starts and no port opens.

It is built on [Vitest](https://vitest.dev) and [Testing Library](https://testing-library.com/docs/react-testing-library/intro/). It adds three helpers on top: `createTestApp()` boots an app with your providers and config, `createTestClient()` sends JSON requests to anything with a `fetch(request)` method, and `renderWithKitr()` from `kitr/testing/react` renders a component inside that app with the query cache already filled.

It runs in your test process only, never in the app bundle. `kitr/testing` has no React in it, so a backend without React uses it as is; `kitr/testing/react` adds the component half. To fake an API your frontend calls, rather than test your own, use [mocks](/packages/mocks) alongside it.

The examples on this page test Acme's order screens at `app.acme.com`: an `/api/orders` API that Ada, Grace and Linus use to create and list orders, and an order list component that shows them.

## Install

```sh
kitr add testing
```

What `kitr add` does:

- Adds `@kitr/testing` and `vitest` to `devDependencies` and installs them. In a project with React it also adds `@testing-library/react`, `@testing-library/dom` and `happy-dom`. Pass `--no-install` to skip the install.
- Adds `'@kitr/testing'` to `packages` in `kitrrc.ts`. It registers no provider, because nothing runs at app startup.
- Writes `vitest.config.ts`, unless one exists. See [Configure](#configure) for both versions.
- Writes `test/example.test.ts`, unless one exists. In a project without React it is an API test of `/api/health` through `createTestClient(server)`; with React it is a one-line `expect(1 + 1).toBe(2)` that proves the runner works.
- Adds a `## kitr: testing` section to `AGENTS.md`: `pnpm test` runs Vitest, components render with `renderWithKitr(<X />, { app, queryData })` from `kitr/testing/react`, APIs are called with `createTestClient(server).get('/api/x')`, and no running backend is needed.

It writes no config file, adds no env variables, adds no scripts and asks no questions. Projects created with `kitr new` already have `"test": "vitest run"` in `package.json`; in an older project, add that script yourself.

Every kit except `blank` includes testing: `app`, `fullstack`, `server`, `saas`, `site`, `realtime`, `desktop` and `mobile`.

`kitr remove testing` takes `'@kitr/testing'` out of `kitrrc.ts`, removes the `@kitr/testing` dependency and the `AGENTS.md` section, then lists files under `app/` and `config/` that still import `kitr/testing`. It leaves `vitest.config.ts`, everything under `test/` and the other dev dependencies in place.

## Configure

`kitr/testing` has no config file. The test runner reads `vitest.config.ts`, which `kitr add testing` writes. In a project with React it reads:

```ts
// vitest.config.ts
import { defineConfig } from 'vitest/config'
import { kitr } from 'kitr/vite'

export default defineConfig({
  plugins: [kitr({ react: true, tailwind: false })],
  test: {
    environment: 'happy-dom',
    include: ['app/**/*.test.{ts,tsx}', 'test/**/*.test.{ts,tsx}'],
  },
})
```

The `kitr()` plugin gives tests the same `#app`, `#server`, `#config` and `#components` import aliases as the app, and the `virtual:kitr/providers` and `virtual:kitr/config` modules. `happy-dom` gives components a DOM to render into. In a project without React the file has no plugin and runs in Node:

```ts
// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    environment: 'node',
    include: ['app/**/*.test.{ts,tsx}', 'test/**/*.test.{ts,tsx}'],
  },
})
```

Tests live next to the code they test (`app/features/orders/order-list.test.tsx`) or under `test/` (`test/orders.test.ts`). Every other [Vitest option](https://vitest.dev/config/) works in this file as usual.

The three helpers take their options per call. `createTestApp(options)` takes the same options as `createApp()`:

| Option | Default | Description |
| --- | --- | --- |
| `providers` | `[]` | Providers to register and boot, in order. Pass `providers` from `virtual:kitr/providers` for the app's real ones. |
| `config` | `{}` | Per-package config keyed like `config/<name>.ts` files: `{ i18n: { ... } }`. |
| `environment` | `'test'` | `'client'`, `'server'` or `'test'`. `createTestApp` sets `'test'` unless you pass another. |
| `mode` | from Vite's `MODE` or `NODE_ENV` | `'development'`, `'production'` or `'test'`. Under Vitest it is `'test'`. |
| `env` | `{}` | The validated env object, exposed as `app.env`. |
| `platform` | from `KITR_PLATFORM` | The platform name from `kitrrc.ts` the app runs as. |

`createTestClient(target, defaults)`:

| Option | Default | Description |
| --- | --- | --- |
| `target` | required | A kitr server, any object with `fetch(request)`, or a base URL string such as `'https://staging.acme.com'`. |
| `defaults.headers` | `{}` | Headers sent with every request. Per-call headers override them. |

`renderWithKitr(ui, options)` from `kitr/testing/react` takes every [Testing Library render option](https://testing-library.com/docs/react-testing-library/api#render-options) plus:

| Option | Default | Description |
| --- | --- | --- |
| `app` | required | The booted app whose providers wrap the component, usually from `createTestApp`. |
| `queryData` | none | Entries `[queryKey, data]` written into the query cache before rendering. Needs the [query](/packages/query) provider in `app`. |
| `wrapper` | none | An extra component rendered inside the app's providers, such as a router. |

## Write your first test

Start with the API, because it needs no DOM. The server in `server/main.ts` is a fetch handler, so the test client calls it directly. This test creates an order as Ada and reads it back:

```ts
// test/orders.test.ts
import { createTestClient } from 'kitr/testing'
import { describe, expect, it } from 'vitest'
import { server } from '#server/main'

describe('orders', () => {
  it('creates an order and reads it back', async () => {
    const client = createTestClient(server)

    const created = await client.post<{ id: string; status: string }>('/api/orders', {
      customer: 'Grace',
      total: 120,
    })
    expect(created.status).toBe(201)
    expect(created.body.status).toBe('open')

    const read = await client.get<{ customer: string }>(`/api/orders/${created.body.id}`)
    expect(read.body.customer).toBe('Grace')
  })
})
```

Run it:

```sh
pnpm test
```

```txt
 ✓ test/orders.test.ts (1 test) 31ms

 Test Files  1 passed (1)
      Tests  1 passed (1)
```

The first request boots the server's app: every provider in `kitrrc.ts` registers and boots, exactly as in `kitr dev`. Nothing listens on a port, so tests run in parallel without clashing.

## Run the tests

`pnpm test` runs `vitest run`: every test once, then exits with a non-zero code if any failed, which is what CI needs. While you work, run Vitest in watch mode so it reruns the tests a change affects:

```sh
pnpm vitest
```

To run one file, or only the tests whose name matches a pattern:

```sh
pnpm test test/orders.test.ts
pnpm test -t "creates an order"
```

Inside a file, `it.only` runs one test and `it.skip` skips one. Remove them before you commit. The [Vitest CLI reference](https://vitest.dev/guide/cli) lists every flag.

## Send requests to your API

`createTestClient` returns one method per verb. `post`, `put` and `patch` take a body; `get` and `delete` do not. Every method takes per-call headers last:

```ts
// test/orders.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

const client = createTestClient(server)

it('updates and deletes an order', async () => {
  const { body: order } = await client.post<{ id: string }>('/api/orders', {
    customer: 'Linus',
    total: 300,
  })

  const paid = await client.patch<{ status: string }>(`/api/orders/${order.id}`, { status: 'paid' })
  expect(paid.body.status).toBe('paid')

  const removed = await client.delete(`/api/orders/${order.id}`)
  expect(removed.status).toBe(204)

  const list = await client.get('/api/orders?status=open&page=2', {
    headers: { 'accept-language': 'de' },
  })
  expect(list.status).toBe(200)
})
```

`put` works the same way as `patch`, for routes you declare with `.put()`. A `.resource()` route uses `PATCH` for updates.

What each request carries:

- `accept: application/json` on every request.
- A body, when you pass one, sent with `JSON.stringify` and `content-type: application/json`. Falsy bodies such as `0`, `false` and `null` are sent too; only `undefined` means no body.
- The query string exactly as you write it in the path. Encode values yourself with `URLSearchParams` when they contain spaces or `&`.

Don't build `new Request(...)` and call `server.fetch()` by hand in every test. The client does it in one line and parses the response for you.

## Read the response

Every call resolves to a `TestResponse` with four fields:

```ts
// test/orders.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

it('returns the new order as JSON', async () => {
  const res = await createTestClient(server).post<{ id: string; customer: string }>(
    '/api/orders',
    { customer: 'Grace', total: 120 },
  )

  res.status // => 201
  res.headers.get('content-type') // => 'application/json;charset=UTF-8'
  res.body // => { id: '1', customer: 'Grace', total: 120, status: 'open' }
  res.response // => the raw Response; its body has already been read

  expect(res.body).toMatchObject({ customer: 'Grace', total: 120 })
})
```

| Field | What it holds |
| --- | --- |
| `status` | The HTTP status code. |
| `headers` | The response `Headers`. |
| `body` | The body parsed as JSON. When the body is not JSON it is the raw text (`'plain words'`); when it is empty, as in a `204`, it is `undefined`. |
| `response` | The raw `Response`, for anything else. Its body is already consumed, so don't call `.json()` on it again. |

The type argument (`post<{ id: string }>`) types `body` only. It does not check the response at run time, so assert the fields you care about.

## Sign requests in

Pass headers once in `defaults` and every request carries them. A per-call header with the same name wins:

```ts
// test/orders.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

it('only lets a signed-in user create orders', async () => {
  const anonymous = createTestClient(server)
  expect((await anonymous.post('/api/orders', { customer: 'Grace', total: 120 })).status).toBe(401)

  const signIn = await anonymous.post<{ token: string }>('/api/auth/sign-in', {
    email: 'ada@acme.com',
    password: 'password',
  })
  const ada = createTestClient(server, { headers: { authorization: `Bearer ${signIn.body.token}` } })

  expect((await ada.post('/api/orders', { customer: 'Grace', total: 120 })).status).toBe(201)

  const asSomeoneElse = await ada.get('/api/auth/me', {
    headers: { authorization: 'Bearer expired-token' },
  })
  expect(asSomeoneElse.status).toBe(401)
})
```

Signing in through the real route keeps the test honest: it uses the same tokens, cookies and guards as production. When many files need a signed-in client, put the sign-in in a helper. [Test your own test helpers](#testing) shows one, with a test for it.

## Assert validation errors

When a controller's `static validation` rejects a body, the server answers `422` with kitr's error shape: a `code`, a `message`, the `status` and `fieldErrors` keyed by field. Assert the fields, not the exact wording, so changing a message does not break the test:

```ts
// test/orders.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

it('rejects an order without a customer or with a negative total', async () => {
  const res = await createTestClient(server).post('/api/orders', { customer: 'G', total: -1 })

  expect(res.status).toBe(422)
  expect(res.body).toMatchObject({ code: 'VALIDATION' })
  expect(Object.keys((res.body as { fieldErrors: object }).fieldErrors)).toEqual([
    'customer',
    'total',
  ])
})
```

The full body for that request, with a [zod](https://zod.dev) schema of `customer: z.string().min(2)` and `total: z.number().positive()`:

```json
{
  "code": "VALIDATION",
  "message": "Validation failed",
  "status": 422,
  "fieldErrors": {
    "customer": ["Too small: expected string to have >=2 characters"],
    "total": ["Too small: expected number to be >0"]
  }
}
```

The same `fieldErrors` reach a form on the client, where [forms](/packages/forms) shows each message under its field.

## Assert error responses

Every error a kitr server sends has the same JSON shape, so one assertion style covers them all. A controller that throws `KitrError.notFound('Order 99')` answers:

```ts
// test/orders.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

it('answers 404 for an order that does not exist', async () => {
  const res = await createTestClient(server).get('/api/orders/99')

  expect(res.status).toBe(404)
  expect(res.body).toEqual({ code: 'NOT_FOUND', message: 'Order 99 not found', status: 404 })
})
```

The codes you will assert most often:

| Status | `code` | Thrown by |
| --- | --- | --- |
| `401` | `UNAUTHORIZED` | `KitrError.unauthorized()`; body message `Authentication required`. |
| `403` | `FORBIDDEN` | `KitrError.forbidden()`; body message `Not allowed`. |
| `404` | `NOT_FOUND` | `KitrError.notFound('Order 99')`, or a path no route matches. |
| `409` | `CONFLICT` | `new KitrError('CONFLICT', 'Order already paid')`. |
| `422` | `VALIDATION` | `static validation` or `KitrError.validation(fieldErrors)`. |
| `500` | `INTERNAL` | Any other thrown error. In production the message becomes `Internal server error`. |

A path with no route answers `404` with `code: 'NOT_FOUND'` and a message like `Cannot find any route matching [GET] http://test/api/nothing`. Requests from the test client go to `http://test`, which is why that host appears.

## Test a deployed API

Pass a URL string instead of the server and the client sends real HTTP requests with the global `fetch`. The same test file then runs against a staging deployment, for a smoke test after a deploy:

```ts
// test/smoke.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'

const baseUrl = process.env.SMOKE_URL ?? 'https://staging.acme.com'

it('serves health and orders', async () => {
  const client = createTestClient(baseUrl, {
    headers: { authorization: `Bearer ${process.env.SMOKE_TOKEN}` },
  })

  expect((await client.get<{ ok: boolean }>('/healthz')).body).toEqual({ ok: true })
  expect((await client.get('/api/orders')).status).toBe(200)
})
```

A trailing slash on the base URL is removed, so `https://staging.acme.com/` works too. `/healthz` is the kitr server's built-in health route. Keep smoke tests out of the default run by giving them their own include pattern, because they need the network and a running deployment.

## Test any fetch handler

The target only needs a `fetch(request)` method that returns a `Response`. That covers a TanStack Start handler, an [h3](https://h3.dev) app, a Cloudflare Worker's default export, or a webhook handler you wrote by hand:

```ts
// test/stripe-webhook.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { handleStripeWebhook } from '#server/webhooks/stripe'

it('marks the invoice paid', async () => {
  const webhook = createTestClient({ fetch: handleStripeWebhook })

  const res = await webhook.post('/webhooks/stripe', {
    type: 'invoice.paid',
    data: { object: { id: 'in_1001', customer_email: 'ada@acme.com' } },
  })

  expect(res.status).toBe(200)
})
```

Wrapping a plain function in `{ fetch: ... }` is enough. The client builds `Request` objects against `http://test`, so read paths from `new URL(request.url).pathname` in the handler, not the host.

## Boot the app without a server

To test a service, a provider or anything else that lives in the container, boot an app with `createTestApp()` and read from it. This one checks that the billing provider binds an `invoices` service with the configured currency:

```ts
// app/features/invoices/invoices.test.ts
import { createTestApp } from 'kitr/testing'
import { expect, it } from 'vitest'
import billingProvider from '#app/providers/billing'

it('binds the invoice service with the configured currency', async () => {
  const app = await createTestApp({
    providers: [billingProvider],
    config: { billing: { currency: 'EUR' } },
  })

  app.status // => 'booted'
  app.environment // => 'test'
  app.config.get('billing') // => { currency: 'EUR' }

  const invoices = app.container.use('invoices')
  expect(invoices.format(1234.5)).toBe('€1,234.50')
})
```

`createTestApp` runs every provider's `register`, then resolves the container, then runs every `boot`. It does not run `ready` or `shutdown`, which only servers call. Each call builds a new app, so one test's services never leak into the next.

Reading a binding nobody registered throws, with the reason in the message:

```ts
app.container.use('mailer')
// => Error: [kitr] No binding named "mailer". Did you add the package that provides it?
```

`kitr/testing` also re-exports `createApp`, for a test that wants to add providers with `app.use()` before booting it itself.

## Use your real providers and config

In a project with React, the `kitr()` plugin in `vitest.config.ts` serves the same two virtual modules the app uses. Import them to boot the app exactly as `app/app.ts` does:

```ts
// app/features/orders/app.test.ts
import { createTestApp } from 'kitr/testing'
import { config } from 'virtual:kitr/config'
import { providers } from 'virtual:kitr/providers'
import { expect, it } from 'vitest'

it('boots with every provider in kitrrc.ts', async () => {
  const app = await createTestApp({ providers, config })

  expect(app.container.has('queryClient')).toBe(true)
  expect(app.container.has('http')).toBe(true)
})
```

`virtual:kitr/providers` is every provider listed in `kitrrc.ts`, in order. `virtual:kitr/config` is every file in `config/`, keyed by file name. Pass `env` when a provider reads `app.env`, because `createTestApp` does not run `app/env.ts`.

A project without React has no plugin and no virtual modules. There, test through the server, which already boots the providers from `kitrrc.ts`, or import `kitrrc.ts` and the config index yourself.

## Replace a service with a fake

Tests should not send real emails or charge real cards. Bind a fake under the same name, after the real provider, and every caller gets the fake. A later binding replaces an earlier one:

```ts
// test/order-confirmation.test.ts
import { defineProvider } from 'kitr/app'
import { createTestApp } from 'kitr/testing'
import { config } from 'virtual:kitr/config'
import { providers } from 'virtual:kitr/providers'
import { expect, it } from 'vitest'
import { sendOrderConfirmation } from '#app/features/orders/confirmation'

it('emails the customer when an order is placed', async () => {
  const sent: Array<{ to: string; subject: string }> = []
  const fakeMailer = defineProvider({
    name: 'fake-mailer',
    register: (app) => app.container.value('mailer', { send: async (m) => void sent.push(m) }),
  })

  const app = await createTestApp({ providers: [...providers, fakeMailer], config })
  await sendOrderConfirmation(app, { id: '1001', email: 'grace@acme.com' })

  expect(sent).toEqual([{ to: 'grace@acme.com', subject: 'Order 1001 confirmed' }])
})
```

To fake a service the API server uses, bind it on `server.app` before the requests that need it. Controllers that read services from `ctx.app.container` then get the fake. This pins the clock so an "orders due today" route gives the same answer every day:

```ts
// test/orders-due.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

it('lists orders due today', async () => {
  await server.boot()
  server.app.container.value('clock', { now: () => new Date('2026-03-01T09:00:00Z') })

  const res = await createTestClient(server).get<{ today: string }>('/api/orders/due')
  expect(res.body.today).toBe('2026-03-01')
})
```

Call `server.boot()` first, so the real provider's binding exists before you replace it. A service a module captured at import time, outside any function, keeps the original; read services inside the handler.

## Render a component

On the client, `renderWithKitr` from `kitr/testing/react` renders a component inside every provider the app has, the same tree `KitrProvider` builds in the browser. Then query the screen with [Testing Library](https://testing-library.com/docs/queries/about):

```tsx
// app/features/orders/order-total.test.tsx
import { screen } from '@testing-library/react'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { expect, it } from 'vitest'
import { OrderTotal } from './order-total'

it('shows the order total', async () => {
  const app = await createTestApp()
  renderWithKitr(<OrderTotal total={120} />, { app })

  expect(screen.getByText('Total: 120')).toBeTruthy()
})
```

`renderWithKitr` returns what Testing Library's `render` returns: `container`, `rerender`, `unmount` and the bound queries. `useApp()` inside the component returns `app`, and `app.mode` is `'test'`. To click and type, use `fireEvent` from `@testing-library/react`, or install [`@testing-library/user-event`](https://testing-library.com/docs/user-event/intro) for events closer to a real user's.

## Seed the query cache

A component that loads data with [query](/packages/query) would try the network on first render. Pass `queryData` and it renders with the data already in the cache. Each entry is a query key and the data under it:

```tsx
// app/features/orders/order-list.test.tsx
import queryProvider from 'kitr/query/provider'
import { screen } from '@testing-library/react'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { expect, it } from 'vitest'
import { OrderList } from './order-list'
import { ordersQuery } from './queries'

it('lists the orders from the cache', async () => {
  const app = await createTestApp({ providers: [queryProvider] })

  renderWithKitr(<OrderList />, {
    app,
    queryData: [[ordersQuery.key(), [{ id: '1', customer: 'Grace', total: 120 }]]],
  })

  expect(await screen.findByText('Grace: 120')).toBeTruthy()
})
```

The query and the component under test read the same key:

```ts
// app/features/orders/queries.ts
import { defineQuery } from 'kitr/query'

export interface Order {
  id: string
  customer: string
  total: number
}

export const ordersQuery = defineQuery<void, Order[]>({
  key: () => ['orders', 'list'],
  fetch: async (_input, { signal }) => {
    const res = await fetch('/api/orders', { signal })
    return (await res.json()) as Order[]
  },
})
```

```tsx
// app/features/orders/order-list.tsx
import { useQuery } from 'kitr/query'
import { ordersQuery } from './queries'

export function OrderList() {
  const { data, isPending } = useQuery(ordersQuery.options())
  if (isPending) return <p>Loading orders</p>
  return (
    <ul>
      {data?.map((order) => (
        <li key={order.id}>
          {order.customer}: {order.total}
        </li>
      ))}
    </ul>
  )
}
```

Take the key from the query definition (`ordersQuery.key()`), not a hand-written array, so the test follows the key when it changes. `queryData` is written with `setQueryData` before the first render. Whether the component refetches it afterwards depends on the query's `staleTime`, so give real queries a `staleTime`, or fake the network with [mocks](#fake-the-network-for-components). When the app has no query provider, `queryData` is ignored.

## Read services in a component

A component that calls `useService('clock')` gets whatever the app's container holds. Register a fake provider and the component renders with it:

```tsx
// app/features/orders/due-badge.test.tsx
import { screen } from '@testing-library/react'
import { defineProvider } from 'kitr/app'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { expect, it } from 'vitest'
import { DueBadge } from './due-badge'

const fixedClock = defineProvider({
  name: 'clock',
  register: (app) => app.container.value('clock', { now: () => new Date('2026-03-01T09:00:00Z') }),
})

it('says an order due today is due today', async () => {
  const app = await createTestApp({ providers: [fixedClock] })
  renderWithKitr(<DueBadge dueAt="2026-03-01" />, { app })

  expect(screen.getByText('Due today')).toBeTruthy()
})
```

The same pattern fakes the [http](/packages/http) client, the [analytics](/packages/analytics) tracker or anything else a component reads from the container.

## Render a component that uses links

`<Link>` and the route hooks need a router above them. Pass one as `wrapper`; `renderWithKitr` renders it inside the app's providers. A root route whose component is the element under test, on a memory history, is enough:

```tsx
// test/with-router.tsx
import {
  createMemoryHistory,
  createRootRoute,
  createRouter,
  RouterProvider,
} from 'kitr/router'
import { type ReactNode, useMemo } from 'react'

/** A wrapper that renders the element under test as the root route at `path`. */
export function withRouter(path = '/') {
  return function RouterWrapper({ children }: { children: ReactNode }) {
    const router = useMemo(() => {
      const rootRoute = createRootRoute({ component: () => children, notFoundComponent: () => null })
      return createRouter({
        routeTree: rootRoute,
        history: createMemoryHistory({ initialEntries: [path] }),
      })
    }, [children])
    return <RouterProvider router={router} />
  }
}
```

```tsx
// app/features/orders/order-row.test.tsx
import { screen } from '@testing-library/react'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { expect, it } from 'vitest'
import { withRouter } from '../../../test/with-router'
import { OrderRow } from './order-row'

it('links to the order', async () => {
  const app = await createTestApp()
  renderWithKitr(<OrderRow order={{ id: '1', customer: 'Grace', total: 120 }} />, {
    app,
    wrapper: withRouter('/orders'),
  })

  const link = await screen.findByRole('link', { name: 'Open' })
  expect(link.getAttribute('href')).toBe('/orders/1')
})
```

The router renders after a tick, so use `findBy...` queries, which wait, not `getBy...`. The helper lives in `test/` because it is shared by many component tests; there is no import alias for that folder, so import it with a relative path.

## Render a whole page

To test a page with its loader, its search params and its layout, build the real router from your route tree with `createKitrRouter` and render it. The router wraps the tree in the app's providers itself, so use Testing Library's plain `render`:

```tsx
// app/routes/orders.test.tsx
import { act, render, screen } from '@testing-library/react'
import queryProvider from 'kitr/query/provider'
import { createKitrRouter, createMemoryHistory, RouterProvider } from 'kitr/router'
import { createTestApp } from 'kitr/testing'
import { expect, it } from 'vitest'
import { routeTree } from '#app/routeTree.gen'

it('renders the orders page from its URL', async () => {
  const app = await createTestApp({ providers: [queryProvider] })
  const router = createKitrRouter({
    routeTree,
    app,
    history: createMemoryHistory({ initialEntries: ['/orders?status=open'] }),
  })

  await act(async () => {
    render(<RouterProvider router={router} />)
    await router.load()
  })

  expect(await screen.findByRole('heading', { name: 'Orders' })).toBeTruthy()
})
```

The page's loader runs for real, so either seed its data with `app.container.use('queryClient').setQueryData(...)` before `router.load()`, or answer its requests with [mocks](/packages/mocks).

## Fake the network for components

When a component really fetches, answer its requests with [mocks](/packages/mocks) instead of seeding the cache. MSW intercepts `fetch` in the test process, so the component, the query and the http client all run as in production:

```tsx
// app/features/orders/order-list.network.test.tsx
import queryProvider from 'kitr/query/provider'
import { screen } from '@testing-library/react'
import { HttpResponse, http, setupNodeMocks } from 'kitr/mocks'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { afterAll, beforeAll, expect, it } from 'vitest'
import { OrderList } from './order-list'

let mocks: Awaited<ReturnType<typeof setupNodeMocks>>
beforeAll(async () => {
  mocks = await setupNodeMocks([
    http.get('*/api/orders', () => HttpResponse.json([{ id: '1', customer: 'Ada', total: 80 }])),
  ])
})
afterAll(() => mocks.close())

it('loads orders from the API', async () => {
  const app = await createTestApp({ providers: [queryProvider] })
  renderWithKitr(<OrderList />, { app })

  expect(screen.getByText('Loading orders')).toBeTruthy()
  expect(await screen.findByText('Ada: 80')).toBeTruthy()
})
```

Seed the cache when the test is about rendering. Fake the network when it is about loading, errors and retries. The mocks guide covers per-test overrides and error responses.

## Choose the test environment per file

The React config runs every file in `happy-dom`. API tests do not need a DOM, and Node's own `Request` and `Response` are what your server uses in production. Put a comment on the first line of the file to run it in Node:

```ts
// @vitest-environment node
// test/invoices.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

it('lists a team’s invoices', async () => {
  const res = await createTestClient(server).get('/api/teams/acme/invoices')
  expect(res.status).toBe(200)
})
```

The comment must come before any import. The `saas`, `site` and `realtime` kits put it on their API tests for the same reason.

## Keep tests isolated

Vitest runs each file in its own module graph, so files never share a server or an app. Tests inside one file do share the imported `server`, including anything its controllers keep in memory. Make each test create the data it reads, and don't assume an order with id `1` exists:

```ts
// test/orders.test.ts
import { createTestClient } from 'kitr/testing'
import { expect, it } from 'vitest'
import { server } from '#server/main'

const client = createTestClient(server)

it('finds the order it just created', async () => {
  const { body } = await client.post<{ id: string }>('/api/orders', { customer: 'Ada', total: 80 })

  expect((await client.get(`/api/orders/${body.id}`)).status).toBe(200)
})
```

For services, prefer a fresh `createTestApp()` per test over one shared at the top of the file. Boot is cheap, and a fresh container means no state carries over.

## Commands

| Command | What it does |
| --- | --- |
| `kitr make:test <name>` | Writes `test/<name>.test.ts` with a test that boots the app. `--force` overwrites an existing file. |

`kitr make:test orders` writes:

```ts
// test/orders.test.ts
import { createTestApp } from 'kitr/testing'
import { describe, expect, it } from 'vitest'

describe('orders', () => {
  it('boots the app', async () => {
    const app = await createTestApp()
    expect(app.status).toBe('booted')
  })

  // HTTP: `const client = createTestClient(server)` with `server` from server/main.ts, then
  // `expect((await client.get('/api/health')).status).toBe(200)`.
})
```

The name is turned into snake case, so `kitr make:test invoice-totals` writes `test/invoice_totals.test.ts`. A `stubs/test.ts` file in your project replaces the template. The command comes with the CLI, so it works before `kitr add testing` too.

## Testing

Shared helpers are code too, and a broken helper makes every test that uses it lie. Test them with an inline fetch handler: an object with a `fetch` method that echoes what it received, so you can assert what the helper sends without booting your server.

This helper signs a client in as one of Acme's users:

```ts
// test/helpers.ts
import { createTestClient } from 'kitr/testing'

type Target = Parameters<typeof createTestClient>[0]

/** A client signed in as `email`, through the real sign-in route. */
export async function signedInClient(target: Target, email: string) {
  const anonymous = createTestClient(target)
  const res = await anonymous.post<{ token: string }>('/api/auth/sign-in', {
    email,
    password: 'password',
  })
  if (res.status !== 201) throw new Error(`Sign-in as ${email} failed with ${res.status}`)
  return createTestClient(target, { headers: { authorization: `Bearer ${res.body.token}` } })
}
```

And its test, which runs in milliseconds and needs no server:

```ts
// test/helpers.test.ts
import { describe, expect, it } from 'vitest'
import { signedInClient } from './helpers'

const fakeApi = {
  async fetch(request: Request) {
    const { pathname } = new URL(request.url)
    if (pathname === '/api/auth/sign-in') {
      const { email } = (await request.json()) as { email: string }
      if (email === 'linus@acme.com') return Response.json({ code: 'UNAUTHORIZED' }, { status: 401 })
      return Response.json({ token: `token-for-${email}` }, { status: 201 })
    }
    return Response.json({
      path: pathname,
      authorization: request.headers.get('authorization'),
      accept: request.headers.get('accept'),
    })
  },
}

describe('signedInClient', () => {
  it('sends the token from sign-in on every request', async () => {
    const ada = await signedInClient(fakeApi, 'ada@acme.com')
    const res = await ada.get<{ path: string; authorization: string; accept: string }>('/api/orders')

    expect(res.status).toBe(200)
    expect(res.body).toEqual({
      path: '/api/orders',
      authorization: 'Bearer token-for-ada@acme.com',
      accept: 'application/json',
    })
  })

  it('lets one request override the token', async () => {
    const grace = await signedInClient(fakeApi, 'grace@acme.com')
    const res = await grace.get<{ authorization: string }>('/api/orders', {
      headers: { authorization: 'Bearer other' },
    })

    expect(res.body.authorization).toBe('Bearer other')
  })

  it('fails loudly when sign-in is refused', async () => {
    await expect(signedInClient(fakeApi, 'linus@acme.com')).rejects.toThrow(
      'Sign-in as linus@acme.com failed with 401',
    )
  })
})
```

The same inline-handler trick tests any code that takes a fetch target: retry wrappers, webhook signers, a client for a partner API.

## Next steps

- [API reference](/packages/testing/api): every export of `kitr/testing` and `kitr/testing/react`.
- [Mocks](/packages/mocks): fake the API your frontend calls, in tests and in the browser.
- [Vitest docs](https://vitest.dev/guide/): matchers, mocking modules, timers, coverage.
- [Testing Library queries](https://testing-library.com/docs/queries/about): which query to use for which element.
- [API](/packages/api): the routes and controllers these tests call.


# Theme API

Source: https://kitr.dev/packages/theme/api

Every export of `kitr/theme`, `kitr/theme/provider`, `kitr/theme/server`, read from the published type definitions. The [guide](/packages/theme) shows them in use.

## kitr/theme

Re-exports `class-variance-authority`, `clsx` unchanged, plus the following.

### dataAttrs

```ts
function dataAttrs(values: Record<string, string | number | boolean | null | undefined>): Record<`data-${string}`, string>;
```

Data-attribute variants for vanilla CSS: `<div {...dataAttrs({ state, size })}>` → `data-state="open"`.

### defineTokens

```ts
function defineTokens<const T extends TokenGroup>(tokens: T, options?: {
  prefix?: string;
}): DefineTokensResult<T>;
```

Turn a nested token object into CSS custom properties with typed names. The prefix defaults to
`kitr`, so `color.primary` becomes `--kitr-color-primary`.

### pick

```ts
function pick<K extends string>(styles: CssModule<K>, ...parts: Array<K | Partial<Record<K, boolean | undefined>> | false | null | undefined>): string;
```

Pick classes from a module with optional conditions: `pick(styles, 'card', { active })`.

### setToastImplementation

```ts
function setToastImplementation(fn: ToastFn | null): void;
```

Replace what `toast` calls: a function with `success`, `error`, `info`, `warning` and `promise` methods.
The theme provider sets sonner's `toast` once it loads; `null` goes back to the console fallback.

### themeFromCookie

```ts
function themeFromCookie(cookieHeader: string | null | undefined, storageKey?: string): ResolvedTheme | undefined;
```

Read the theme cookie on the server to pass as `initialResolved`.

### ThemeProvider

```ts
function ThemeProvider({ children, defaultTheme, storageKey, attribute, initialResolved, colors }: ThemeProviderProps): import("react").JSX.Element;
```

Light/dark/system with no flash: pair with `<ThemeScript />` in the document head.
Sets `data-theme="light|dark"` on <html>, which the Tailwind preset and styles.css read.

### ThemeScript

```ts
function ThemeScript({ storageKey, attribute }: {
  storageKey?: string;
  attribute?: string;
}): import("react").JSX.Element;
```

Inline script for the document head; applies the stored theme before first paint.

### toastError

```ts
function toastError(error: unknown, fallbackMessage?: string): void;
```

Show a KitrError (or anything) as an error toast with its message.

### useTheme

```ts
function useTheme(): ThemeContextValue;
```

The current theme and the functions that change it: `{ theme, resolved, setTheme, toggle }`.
Throws when no `ThemeProvider` (or the theme provider in `kitrrc.ts`) is above the component.

### vars

```ts
function vars(values: Record<`--${string}`, string | number>): Record<string, string>;
```

Build a `style` object from CSS variables: `vars({ '--gap': '8px' })`.

### darkTokens

```ts
const darkTokens: DefineTokensResult<{
  readonly color: {
    readonly background: "oklch(16% 0.01 260)";
    readonly foreground: "oklch(95% 0.005 260)";
    readonly muted: "oklch(24% 0.01 260)";
    readonly mutedForeground: "oklch(70% 0.02 260)";
    readonly border: "oklch(30% 0.01 260)";
    readonly primary: "oklch(70% 0.17 262)";
    readonly primaryForeground: "oklch(16% 0.01 260)";
    readonly destructive: "oklch(65% 0.2 27)";
    readonly destructiveForeground: "oklch(16% 0 0)";
    readonly ring: "oklch(70% 0.17 262)";
  };
}>;
```

kitr's dark colour tokens, the values `kitr/theme/styles.css` sets under `[data-theme="dark"]`. Radius, font and shadow are shared with the light set.

### defaultTokens

```ts
const defaultTokens: DefineTokensResult<{
  readonly color: {
    readonly background: "oklch(99% 0 0)";
    readonly foreground: "oklch(20% 0.01 260)";
    readonly muted: "oklch(96% 0.005 260)";
    readonly mutedForeground: "oklch(50% 0.02 260)";
    readonly border: "oklch(90% 0.01 260)";
    readonly primary: "oklch(55% 0.2 262)";
    readonly primaryForeground: "oklch(99% 0 0)";
    readonly destructive: "oklch(55% 0.22 27)";
    readonly destructiveForeground: "oklch(99% 0 0)";
    readonly ring: "oklch(55% 0.2 262)";
  };
  readonly radius: {
    readonly sm: "0.25rem";
    readonly md: "0.5rem";
    readonly lg: "0.75rem";
  };
  readonly font: {
    readonly sans: "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
    readonly mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
  };
  readonly shadow: {
    readonly sm: "0 1px 2px oklch(0% 0 0 / 0.06)";
    readonly md: "0 4px 12px oklch(0% 0 0 / 0.08)";
  };
}>;
```

kitr's light (default) tokens, the values `kitr/theme/styles.css` sets on `:root`. Override them in `app/styles/tokens.css`.

### defineConfig

```ts
const defineConfig: <const C extends ThemeConfig>(config: C) => C;
```

Type-check `config/theme.ts`: returns the object unchanged, with autocomplete for every `ThemeConfig` option.

### toast

```ts
const toast: ToastFn;
```

Show a toast: `toast('Saved')`, `toast.success()`, `.error()`, `.info()`, `.warning()` and `.promise()`.
Goes to sonner when it is installed and loaded, and to the console otherwise.

### DefineTokensResult

```ts
interface DefineTokensResult<T extends TokenGroup> {
  /** The token tree as passed in. */
  tokens: T;
  /** A `var()` reference for a path: `var('color.primary')` → `var(--kitr-color-primary)`. */
  var: (path: TokenPath<T>) => `var(--${string})`;
  /** The CSS variable name for a path: `name('color.primary')` → `--kitr-color-primary`. */
  name: (path: TokenPath<T>) => `--${string}`;
  /** `:root { --kitr-...: ...; }` ready to drop into a stylesheet. */
  css: (selector?: string) => string;
  /** Flat `{ '--kitr-color-primary': '#...' }` for inline styles or runtime theming. */
  flat: () => Record<string, string>;
}
```

What `defineTokens` returns: the tree itself plus helpers that name, reference and emit its CSS variables.

### ThemeConfig

```ts
interface ThemeConfig {
  /** 'light' | 'dark' | 'system'. Default 'system'. */
  default?: 'light' | 'dark' | 'system';
  /** Storage key (localStorage and the cookie the server reads). Default 'kitr-theme'. */
  storageKey?: string;
  /** Attribute set on <html>. Default 'data-theme'. */
  attribute?: string;
  /** Typed slot for token overrides. Not read by kitr yet; override `--kitr-*` variables in `app/styles/tokens.css`. */
  tokens?: {
    light?: TokenGroup;
    dark?: TokenGroup;
  };
  /** `<meta name="theme-color">` and native window chrome per resolved theme. */
  colors?: {
    light?: string;
    dark?: string;
  };
  /** Where `kitr ui add` pulls components from. Any shadcn-compatible registry. */
  registry?: string;
  /** Where components are written. Default `app/components/ui`. */
  componentsDir?: string;
  /** The sonner toaster the provider mounts once `sonner` is installed. */
  toaster?: {
    /** Where toasts appear. Default `'bottom-right'`. */
    position?: 'top-right' | 'top-center' | 'bottom-right' | 'bottom-center';
    /** Coloured success, error, info and warning toasts. Default `true`. */
    richColors?: boolean;
  };
}
```

The options of `config/theme.ts`: the default theme, where it is stored, window colours, the toaster and the component registry.

### ThemeProviderProps

```ts
interface ThemeProviderProps {
  /** The tree that can call `useTheme()`. */
  children: ReactNode;
  /** The theme before the user picks one. Default `'system'`. */
  defaultTheme?: Theme;
  /** The `localStorage` key and cookie name holding the choice. Default `'kitr-theme'`. */
  storageKey?: string;
  /** The attribute set on `<html>` to `light` or `dark`. Default `'data-theme'`. */
  attribute?: string;
  /** Theme known on the server (e.g. from a cookie) to avoid a flash. */
  initialResolved?: ResolvedTheme;
  /** `<meta name="theme-color">` per resolved theme, which native shells and PWAs show as window chrome. */
  colors?: {
    light?: string;
    dark?: string;
  };
}
```

Props of `ThemeProvider`. The theme provider in `kitrrc.ts` fills them from `config/theme.ts`.

### TokenGroup

```ts
interface TokenGroup {
  [key: string]: TokenLeaf | TokenGroup;
}
```

A nested object of tokens, such as `{ color: { primary: '#0ea5e9' } }`. Each leaf becomes one CSS variable.

### CssModule

```ts
/** Type a CSS Modules import so `styles.foo` is checked. Generate the `.d.ts` with `kitr css:types`. */
type CssModule<K extends string> = {
  readonly [P in K]: string;
};
```

Type a CSS Modules import so `styles.foo` is checked. Generate the `.d.ts` with `kitr css:types`.

### ResolvedTheme

```ts
type ResolvedTheme = 'light' | 'dark';
```

The theme on screen once `'system'` is resolved: always `'light'` or `'dark'`.

### Theme

```ts
type Theme = 'light' | 'dark' | 'system';
```

The user's choice: a fixed theme, or `'system'` to follow the operating system.

### TokenLeaf

```ts
/** A single token value: a CSS string such as `'0.5rem'`, or a number written without a unit. */
type TokenLeaf = string | number;
```

A single token value: a CSS string such as `'0.5rem'`, or a number written without a unit.

### TokenPath

```ts
type TokenPath<T, Prefix extends string = ''> = {
  [K in keyof T & string]: T[K] extends TokenLeaf ? `${Prefix}${K}` : TokenPath<T[K], `${Prefix}${K}.`>;
}[keyof T & string];
```

Every dotted path to a leaf of a token tree (`'color.primary'`), so token names are checked at compile time.

## kitr/theme/provider

### themeProvider

```ts
const themeProvider: import("@kitr/core").KitrProvider;
```

Wraps the app in ThemeProvider with `config/theme.ts` and mounts the toaster (sonner, if installed).
Listed in kitrrc.ts as `() => import('@kitr/theme/provider')`. Pair with `<ThemeScript />` in the document head.

## kitr/theme/server

### themeFromCookie

```ts
function themeFromCookie(cookieHeader: string | null | undefined, storageKey?: string): ResolvedTheme | undefined;
```

Read the theme cookie on the server to pass as `initialResolved`.

### ResolvedTheme

```ts
type ResolvedTheme = 'light' | 'dark';
```

The theme on screen once `'system'` is resolved: always `'light'` or `'dark'`.

### Theme

```ts
type Theme = 'light' | 'dark' | 'system';
```

The user's choice: a fixed theme, or `'system'` to follow the operating system.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Theme

Source: https://kitr.dev/packages/theme

Users expect dark mode, a page that does not flash white before it turns dark, and buttons that look the same on every screen. `kitr/theme` gives your app light, dark and system themes that follow the operating system and remember the user's choice, a set of design tokens as CSS variables, toasts, and the settings `kitr ui add` uses to copy ready-made components into your app. It is built on [CSS custom properties](https://developer.mozilla.org/docs/Web/CSS/Using_CSS_custom_properties), [sonner](https://sonner.emilkowal.ski) for toasts and [shadcn/ui](https://ui.shadcn.com)-compatible registries for components, and adds a theme provider, a no-flash script and typed token helpers on top.

It runs in the browser, and on the server during server rendering. For utility classes on top of the same tokens, add [tailwind](/packages/tailwind) as well; for a server-only project there is nothing to theme.

This guide follows Acme's dashboard at `app.acme.com`: Ada adds a dark mode toggle, brands the colours, shows a toast when Grace saves an invoice, and copies in a few components.

## Install

```sh
kitr add theme
```

What `kitr add` does:

- Adds [react](/packages/react) first if the project does not have it, because theme requires it.
- Installs `@kitr/theme`.
- Adds the provider to `kitrrc.ts`: `() => import('@kitr/theme/provider')`, and `'@kitr/theme'` to `packages`.
- Writes `config/theme.ts` (shown under Configure).
- Writes `app/styles/tokens.css`, an empty `:root` block for your token overrides.
- Adds a `theme` section to `AGENTS.md`: use `useTheme()`, put `<ThemeScript />` in the document head, take colours and radii from the `--kitr-*` variables, keep components in `app/components/ui/` and add them with `kitr ui add`, and use Hugeicons through `<Icon />`.
- Adds no environment variables and no scripts. When it finishes it prints `Pull components with kitr ui add button input form`.

`kitr add` skips files that already exist. It asks no questions; `--no-install` skips the package manager and `--dry-run` prints the plan.

```sh
kitr add theme --dry-run
```

The `app`, `fullstack`, `saas`, `site`, `realtime`, `desktop` and `mobile` kits include theme, and copy in a starter set of components with it (`icon`, `button`, `input`, `card`, `theme-toggle` and more). The `blank` kit does not.

The base stylesheet, `kitr/theme/styles.css`, is linked by the root route that [router](/packages/router) writes, so it is in place before you add theme. With [tailwind](/packages/tailwind), `app/styles/app.css` imports it instead.

`kitr remove theme` removes the provider, the `packages` entry, the dependency, `config/theme.ts` and the `AGENTS.md` section. `app/styles/tokens.css` and the components in `app/components/ui/` stay, because they are yours.

## Configure

`kitr add theme` writes this file:

```ts
// config/theme.ts
import { defineConfig } from 'kitr/theme'

export default defineConfig({
  default: 'system',
  // Window chrome / <meta name="theme-color"> per theme.
  colors: { light: '#ffffff', dark: '#0a0a0a' },
  // Any shadcn-compatible registry for `kitr ui add`. Default: kitr's.
  // registry: 'https://raw.githubusercontent.com/kitrjs/kitr/main/registry/dist',
  componentsDir: 'app/components/ui',
})
```

| Option | Default | Description |
| --- | --- | --- |
| `default` | `'system'` | The theme before the user picks one: `'light'`, `'dark'` or `'system'`. |
| `storageKey` | `'kitr-theme'` | The `localStorage` key and cookie name that hold the user's choice. Pass the same value to `<ThemeScript>`. |
| `attribute` | `'data-theme'` | The attribute set on `<html>` to `light` or `dark`. Pass the same value to `<ThemeScript>`. |
| `colors.light` | none | `<meta name="theme-color">` while the light theme shows. Browsers and installed PWAs tint their chrome with it. |
| `colors.dark` | none | The same, for the dark theme. |
| `toaster.position` | `'bottom-right'` | Where toasts appear: `'top-right'`, `'top-center'`, `'bottom-right'` or `'bottom-center'`. |
| `toaster.richColors` | `true` | Coloured success, error, info and warning toasts. |
| `registry` | kitr's registry | Where `kitr ui add` and `kitr ui list` fetch components: a URL or a local directory. |
| `componentsDir` | `app/components/ui` | Where `kitr ui add` writes components. |
| `tokens.light`, `tokens.dark` | none | Typed slot for token overrides. Nothing reads it yet; override tokens in `app/styles/tokens.css` (see "Brand the colours"). |

| Variable | Used for |
| --- | --- |
| `KITR_REGISTRY` | Overrides `registry` for one `kitr ui add` or `kitr ui list` run, such as in CI. |

The config is read once, when the app is created. `useConfig('theme')` from [react](/packages/react) returns it in a component.

## Add a dark mode toggle

`useTheme()` returns the current choice and the functions that change it. Any component under the app can call it:

```tsx
// app/components/theme-button.tsx
import { useTheme } from 'kitr/theme'

export function ThemeButton() {
  const { resolved, toggle } = useTheme()
  return (
    <button type="button" onClick={toggle}>
      {resolved === 'dark' ? 'Switch to light' : 'Switch to dark'}
    </button>
  )
}
```

Put it in the root layout:

```tsx
// app/routes/__root.tsx
// ...
import { ThemeButton } from '#app/components/theme-button'

function RootLayout() {
  return (
    <RootDocument>
      <nav style={{ display: 'flex', gap: 12, padding: 12 }}>
        <Link to="/">Home</Link>
        <ThemeButton />
      </nav>
      <Outlet />
    </RootDocument>
  )
}
```

Click it and the page turns dark: `<html>` gets `data-theme="dark"` and `style="color-scheme: dark"`, every `--kitr-*` variable switches to its dark value, and the choice is saved, so a reload keeps it.

| Field | What it is |
| --- | --- |
| `theme` | The user's choice: `'light'`, `'dark'` or `'system'`. |
| `resolved` | What shows on screen: `'light'` or `'dark'`. With `'system'`, it follows the operating system and updates when the OS setting changes. |
| `setTheme(theme)` | Sets the choice and saves it to `localStorage` and a one-year cookie. |
| `toggle()` | Switches to the opposite of `resolved` and saves that, which leaves `'system'`. |

For a styled toggle with an icon, copy the registry's version instead: `kitr ui add theme-toggle` writes `app/components/ui/theme-toggle.tsx` (plus `button` and `icon`), and you render `<ThemeToggle />`.

## Let users pick light, dark or system

`toggle()` is a two-way switch. To offer "match my system" as well, call `setTheme` from a select:

```tsx
// app/features/settings/appearance.tsx
import { type Theme, useTheme } from 'kitr/theme'

export function AppearanceSetting() {
  const { theme, setTheme } = useTheme()
  return (
    <label>
      Appearance
      <select value={theme} onChange={(e) => setTheme(e.target.value as Theme)}>
        <option value="system">Match system</option>
        <option value="light">Light</option>
        <option value="dark">Dark</option>
      </select>
    </label>
  )
}
```

With `system` saved, `resolved` follows the OS: when Linus's laptop switches to dark at sunset, the dashboard does too, without a reload. A stored value other than `light`, `dark` or `system` is ignored and `default` applies.

## Avoid a flash on load

React applies the theme after it hydrates, a moment after the first paint. Without help, a dark-mode user sees a white page flash first. `<ThemeScript />` is a tiny inline script that reads the saved choice and sets `data-theme` before anything paints. Put it first in the document head:

```tsx
// app/routes/__root.tsx
import type { KitrRouterContext } from 'kitr/router'
import { HeadContent, Outlet, Scripts, createRootRouteWithContext } from 'kitr/router'
import { ThemeScript } from 'kitr/theme'
import type { ReactNode } from 'react'
import css0 from 'kitr/theme/styles.css?url'

export const Route = createRootRouteWithContext<KitrRouterContext>()({
  head: () => ({
    meta: [{ charSet: 'utf-8' }, { name: 'viewport', content: 'width=device-width, initial-scale=1' }],
    links: [{ rel: 'stylesheet', href: css0 }],
  }),
  component: () => (
    <RootDocument>
      <Outlet />
    </RootDocument>
  ),
})

function RootDocument({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <ThemeScript />
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}
```

The script changes `<html>` before React hydrates it, so React would warn that the attribute differs from the server's HTML; `suppressHydrationWarning` on `<html>` tells it this one difference is expected.

The root route that `kitr add router` writes does not include `<ThemeScript />`, so add it yourself. It works the same in `ssr`, `static` and `spa` modes and in desktop and mobile shells, because it only reads `localStorage`.

If you changed `storageKey` or `attribute` in `config/theme.ts`, pass the same values: `<ThemeScript storageKey="acme-theme" attribute="data-mode" />`. The script reads its props, not the config. It escapes both values, so a key containing `</script>` cannot break out of the tag.

## Render the saved theme on the server

In `ssr` mode the server can send the right theme in the HTML itself. `setTheme` writes the choice to a cookie as well as to `localStorage`, and `themeFromCookie` reads it from the request's `Cookie` header:

```ts
// app/features/theme/read-theme.ts
import { createServerFn } from '@tanstack/react-start'
import { getRequest } from '@tanstack/react-start/server'
import { themeFromCookie } from 'kitr/theme/server'

/** Runs on the server only: the visitor's theme, straight from the request cookie. */
export const readTheme = createServerFn({ method: 'GET' }).handler(
  () => themeFromCookie(getRequest().headers.get('cookie')) ?? null,
)
```

```tsx
// app/routes/__root.tsx
// ...
import { readTheme } from '#app/features/theme/read-theme'

export const Route = createRootRouteWithContext<KitrRouterContext>()({
  loader: () => readTheme(),
  component: RootLayout,
})

function RootDocument({ children }: { children: ReactNode }) {
  const theme = Route.useLoaderData()
  return (
    <html lang="en" data-theme={theme ?? undefined} suppressHydrationWarning>
      <head>
        <ThemeScript />
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}
```

`themeFromCookie` returns only `'light'` or `'dark'`:

```ts
import { themeFromCookie } from 'kitr/theme/server'

themeFromCookie('session=abc; kitr-theme=dark') // => 'dark'
themeFromCookie('kitr-theme=system') // => undefined (the server cannot know the OS setting)
themeFromCookie(null) // => undefined
themeFromCookie('acme-theme=light', 'acme-theme') // => 'light', with a custom storageKey
```

When it returns `undefined`, keep `<ThemeScript />` to resolve `system` in the browser. Keep it in any case: it covers static pages and the shells, where there is no request.

## Color the window chrome and status bar

`colors` in `config/theme.ts` keeps `<meta name="theme-color">` in step with the theme. Browsers that support the tag tint their toolbar, and installed PWAs their title bar, with this colour:

```ts
// config/theme.ts
import { defineConfig } from 'kitr/theme'

export default defineConfig({
  default: 'system',
  colors: { light: '#ffffff', dark: '#0b1020' },
  componentsDir: 'app/components/ui',
})
```

On every change of `resolved`, the provider sets the tag's `content` to `colors.light` or `colors.dark`, and creates the tag if the page has none. Pick the same colour as `--kitr-color-background` so the chrome blends into the page. kitr only writes the tag; inside the [desktop](/packages/desktop) and [mobile](/packages/mobile) shells, whether the window or status bar follows it depends on the shell's web view.

## Use the tokens in CSS

`kitr/theme/styles.css` defines every token as a `--kitr-*` variable on `:root`, with dark values under `[data-theme="dark"]`. Use them in any stylesheet and the component follows the theme without a line of JavaScript:

```css
/* app/features/invoices/invoice-card.module.css */
.card {
  background: var(--kitr-color-background);
  color: var(--kitr-color-foreground);
  border: 1px solid var(--kitr-color-border);
  border-radius: var(--kitr-radius-md);
  box-shadow: var(--kitr-shadow-sm);
  font-family: var(--kitr-font-sans);
}
.overdue {
  border-color: var(--kitr-color-destructive);
}
```

| Token | Light | Dark |
| --- | --- | --- |
| `--kitr-color-background` | `oklch(99% 0 0)` | `oklch(16% 0.01 260)` |
| `--kitr-color-foreground` | `oklch(20% 0.01 260)` | `oklch(95% 0.005 260)` |
| `--kitr-color-muted` | `oklch(96% 0.005 260)` | `oklch(24% 0.01 260)` |
| `--kitr-color-mutedForeground` | `oklch(50% 0.02 260)` | `oklch(70% 0.02 260)` |
| `--kitr-color-border` | `oklch(90% 0.01 260)` | `oklch(30% 0.01 260)` |
| `--kitr-color-primary` | `oklch(55% 0.2 262)` | `oklch(70% 0.17 262)` |
| `--kitr-color-primaryForeground` | `oklch(99% 0 0)` | `oklch(16% 0.01 260)` |
| `--kitr-color-destructive` | `oklch(55% 0.22 27)` | `oklch(65% 0.2 27)` |
| `--kitr-color-destructiveForeground` | `oklch(99% 0 0)` | `oklch(16% 0 0)` |
| `--kitr-color-ring` | `oklch(55% 0.2 262)` | `oklch(70% 0.17 262)` |
| `--kitr-radius-sm`, `-md`, `-lg` | `0.25rem`, `0.5rem`, `0.75rem` | same |
| `--kitr-font-sans`, `--kitr-font-mono` | the system UI and monospace stacks | same |
| `--kitr-shadow-sm`, `--kitr-shadow-md` | soft shadows at 6% and 8% black | same |

Don't hard-code `#fff` or `rgb(...)` in a component. A hard-coded colour does not change with the theme, and it does not change when Acme rebrands.

The same tokens exist in JavaScript as `defaultTokens` and `darkTokens`:

```ts
import { darkTokens, defaultTokens } from 'kitr/theme'

defaultTokens.var('color.primary') // => 'var(--kitr-color-primary)'
defaultTokens.name('radius.md') // => '--kitr-radius-md'
defaultTokens.tokens.radius.md // => '0.5rem'
darkTokens.tokens.color.background // => 'oklch(16% 0.01 260)'
```

## Brand the colours

To change a token for the whole app, override its variable in `app/styles/tokens.css`. Acme's brand is a teal primary:

```css
/* app/styles/tokens.css */
:root {
  --kitr-color-primary: oklch(60% 0.12 190);
  --kitr-color-ring: oklch(60% 0.12 190);
  --kitr-radius-md: 0.375rem;
}
[data-theme="dark"] {
  --kitr-color-primary: oklch(72% 0.11 190);
  --kitr-color-ring: oklch(72% 0.11 190);
}
```

`kitr add theme` writes this file but does not link it anywhere. Link it after `kitr/theme/styles.css` in the root route, so your values come later in the cascade and win:

```tsx
// app/routes/__root.tsx
import css0 from 'kitr/theme/styles.css?url'
import tokens from '#app/styles/tokens.css?url'

export const Route = createRootRouteWithContext<KitrRouterContext>()({
  head: () => ({
    links: [
      { rel: 'stylesheet', href: css0 },
      { rel: 'stylesheet', href: tokens },
    ],
  }),
  // ...
})
```

With [tailwind](/packages/tailwind), import it in `app/styles/app.css` after `kitr/theme/styles.css` instead: `@import './tokens.css';`.

## Define your own tokens

`defineTokens` turns a nested object into CSS variables with typed names. Use it for values kitr has no token for, such as Acme's invoice status colours:

```ts
// app/styles/acme-tokens.ts
import { defineTokens } from 'kitr/theme'

export const acme = defineTokens(
  {
    status: { paid: 'oklch(65% 0.15 150)', overdue: 'oklch(60% 0.2 27)' },
    space: { card: 16 },
  },
  { prefix: 'acme' },
)

acme.name('status.paid') // => '--acme-status-paid'
acme.var('status.overdue') // => 'var(--acme-status-overdue)'
acme.flat()
// => { '--acme-status-paid': 'oklch(65% 0.15 150)', '--acme-status-overdue': 'oklch(60% 0.2 27)', '--acme-space-card': '16' }
acme.css()
// => ':root {\n  --acme-status-paid: oklch(65% 0.15 150);\n  --acme-status-overdue: oklch(60% 0.2 27);\n  --acme-space-card: 16;\n}\n'
```

`acme.var('status.unpaid')` is a type error, because the path is checked against the object. Numbers are written as they are, without a unit; write `'16px'` when the CSS needs one. The prefix defaults to `kitr`.

Emit the variables once, from the root layout, or spread `flat()` into a `style` to scope them to one element:

```tsx
// app/features/invoices/invoice-status.tsx
import { acme } from '#app/styles/acme-tokens'

export function InvoiceStatus({ status }: { status: 'paid' | 'overdue' }) {
  return (
    <span style={{ ...acme.flat(), color: acme.var(`status.${status}`) }}>
      {status === 'paid' ? 'Paid' : 'Overdue'}
    </span>
  )
}
```

```tsx
// app/routes/__root.tsx
import { acme } from '#app/styles/acme-tokens'

// inside <head>, after <HeadContent />:
<style>{acme.css()}</style>
```

## Style with CSS Modules

Without Tailwind, CSS Modules plus three small helpers cover most styling. `kitr css:types` writes a `.d.ts` next to each `*.module.css`, so class names are checked:

```sh
kitr css:types
```

```ts
// app/features/invoices/invoice-card.module.css.d.ts
// Generated by `kitr css:types`. Do not edit.
declare const classes: {
  readonly card: string
  readonly overdue: string
}
export default classes
```

`pick(styles, ...parts)` joins class names, with conditions in an object:

```tsx
// app/features/invoices/invoice-card.tsx
import { pick } from 'kitr/theme'
import styles from './invoice-card.module.css'

export function InvoiceCard({ id, total, overdue }: { id: string; total: number; overdue: boolean }) {
  return (
    <article className={pick(styles, 'card', { overdue })}>
      {id}: ${total}
    </article>
  )
}
// overdue → class="card_x1 overdue_x2" (the hashed names from the module)
```

`pick` skips `false`, `null` and `undefined`, so `pick(styles, 'card', isOpen && 'overdue')` works too. `pick(styles, 'crad')` is a type error. To type a module by hand, use `CssModule<'card' | 'overdue'>`.

## Pass values to CSS

`vars()` builds a `style` object of CSS variables, so a component passes a number to its stylesheet without inline colour or size rules:

```tsx
// app/features/projects/progress-bar.tsx
import { vars } from 'kitr/theme'
import styles from './progress-bar.module.css'

export function ProgressBar({ done }: { done: number }) {
  return <div className={styles.track} style={vars({ '--progress': `${done}%` })} />
}
// vars({ '--progress': '40%', '--gap': 8 }) => { '--progress': '40%', '--gap': '8' }
```

```css
/* app/features/projects/progress-bar.module.css */
.track {
  height: 0.5rem;
  border-radius: var(--kitr-radius-sm);
  background: linear-gradient(
    to right,
    var(--kitr-color-primary) var(--progress),
    var(--kitr-color-muted) var(--progress)
  );
}
```

## Style states with data attributes

`dataAttrs()` turns an object into `data-*` attributes, so plain CSS can target a component's state with an attribute selector:

```tsx
// app/features/orders/order-row.tsx
import { dataAttrs } from 'kitr/theme'

export function OrderRow({ status, selected }: { status: 'open' | 'shipped'; selected: boolean }) {
  return <tr className="order-row" {...dataAttrs({ status, isSelected: selected })} />
}
// dataAttrs({ status: 'open', isSelected: true }) => { 'data-status': 'open', 'data-is-selected': '' }
// dataAttrs({ status: 'shipped', isSelected: false }) => { 'data-status': 'shipped' }
```

```css
/* app/styles/orders.css */
.order-row[data-status="shipped"] {
  color: var(--kitr-color-mutedForeground);
}
.order-row[data-is-selected] {
  background: var(--kitr-color-muted);
}
```

Keys become kebab-case. `true` gives an empty attribute; `false`, `null` and `undefined` leave it out; numbers become strings.

## Build component variants

`kitr/theme` re-exports [class-variance-authority](https://cva.style) as `cva` (with `VariantProps` and its `cx` as `cvaCx`) and [clsx](https://github.com/lukeed/clsx) as `clsx` and `cx`. The registry components use them, and so can yours:

```tsx
// app/components/ui/badge.tsx
import { cva, cx, type VariantProps } from 'kitr/theme'

const badge = cva('badge', {
  variants: {
    tone: { neutral: 'badge-neutral', success: 'badge-success', danger: 'badge-danger' },
  },
  defaultVariants: { tone: 'neutral' },
})

export function Badge({
  tone,
  className,
  children,
}: VariantProps<typeof badge> & { className?: string; children: string }) {
  return <span className={cx(badge({ tone }), className)}>{children}</span>
}
// badge({ tone: 'success' }) => 'badge badge-success'
// cx('badge', { active: true, muted: false }) => 'badge active'
```

With [tailwind](/packages/tailwind), use its `cn()` instead of `cx`, which also merges conflicting utility classes.

## Show toasts

`toast` shows a short message. Call it from anywhere: a component, an event handler or a package.

```tsx
// app/features/invoices/save-invoice-button.tsx
import { toast, toastError } from 'kitr/theme'

export function SaveInvoiceButton({ id }: { id: string }) {
  async function save() {
    try {
      await fetch(`/api/invoices/${id}`, { method: 'PUT' })
      toast.success(`Invoice ${id} saved`)
    } catch (error) {
      toastError(error)
    }
  }
  return (
    <button type="button" onClick={save}>
      Save
    </button>
  )
}
```

| Call | Shows |
| --- | --- |
| `toast(message, options?)` | A plain toast. `options` go to sonner, such as `{ description, duration }`. |
| `toast.success(message)`, `.info()`, `.warning()`, `.error()` | A coloured toast of that kind. |
| `toast.promise(promise, { loading, success, error })` | A loading toast that turns into success or error when the promise settles. Returns the promise. |
| `toastError(error, fallback?)` | `toast.error` with the error's `message`, or `fallback` (default `'Something went wrong'`) when it has none. |

`toast.promise` keeps the user informed during a slow save, and returns the same promise so you can still await it:

```tsx
// app/features/invoices/send-invoice.ts
import { toast } from 'kitr/theme'

export function sendInvoice(id: string) {
  return toast.promise(fetch(`/api/invoices/${id}/send`, { method: 'POST' }), {
    loading: `Sending ${id} to grace@acme.com…`,
    success: `Invoice ${id} sent`,
    error: `Could not send ${id}`,
  })
}
```

Toasts are drawn by [sonner](https://sonner.emilkowal.ski), which is optional. Install it with the registry component:

```sh
kitr ui add sonner
```

Once `sonner` is installed, the theme provider loads it and mounts its `<Toaster />` on `document.body` after the first render, with `position` and `richColors` from `toaster` in `config/theme.ts`. You don't mount anything. The command also copies `app/components/ui/sonner.tsx`, a `Toaster` that follows the current theme; you only need it to render a toaster somewhere other than the provider's.

Without sonner, every call goes to the console instead, so a package can call `toast` without making sonner a dependency:

```ts
import { toast, toastError } from 'kitr/theme'

toast('Draft saved') // console.info('[toast] Draft saved')
toast.success('Invoice inv_1 saved') // console.info('[toast:success] Invoice inv_1 saved')
toast.warning('Invoice inv_2 is overdue') // console.warn('[toast:warning] Invoice inv_2 is overdue')
toastError(new Error('Payment declined')) // console.error('[toast:error] Payment declined')
```

Calls made before sonner has loaded, such as during the first render, also go to the console.

## Send toasts to another toast library

`setToastImplementation` replaces what `toast` calls. Give it a function with `success`, `error`, `info`, `warning` and `promise` methods. The provider does this for sonner; do it yourself to route toasts to another library or to your own UI:

```ts
// app/providers/toast_provider.ts
import { defineProvider } from 'kitr/app'
import { setToastImplementation } from 'kitr/theme'
import { notify } from '#app/components/notify'

export default defineProvider({
  name: 'toast',
  boot() {
    setToastImplementation(
      Object.assign((message: string) => notify({ tone: 'neutral', message }), {
        success: (message: string) => notify({ tone: 'success', message }),
        error: (message: string) => notify({ tone: 'danger', message }),
        info: (message: string) => notify({ tone: 'neutral', message }),
        warning: (message: string) => notify({ tone: 'warning', message }),
        promise: <T>(promise: Promise<T>) => promise,
      }),
    )
  },
})
```

`setToastImplementation(null)` goes back to the console fallback. If sonner is installed too, the theme provider sets sonner again when its toaster loads, so use one or the other.

## Add components

`kitr ui add` copies components from a shadcn-compatible registry into `app/components/ui/`. The files are yours to edit; nothing is imported from a package at run time.

```sh
kitr ui add button input card dialog
```

```tsx
// app/features/projects/new-project-card.tsx
import { Button } from '#components/ui/button'
import { Card } from '#components/ui/card'

export function NewProjectCard() {
  return (
    <Card>
      <h2>New project</h2>
      <Button onClick={() => console.info('create project')}>Create</Button>
    </Card>
  )
}
```

The components use the `--kitr-*` tokens and `cva`, so they follow the theme and your token overrides. `kitr ui add` also copies their registry dependencies (`theme-toggle` brings `button` and `icon`) and installs the npm packages they need (`icon` installs `@hugeicons/react` and `@hugeicons/core-free-icons`).

| Component | What it is |
| --- | --- |
| `app-shell` | Sidebar and top bar layout with navigation links, a user menu slot and the theme toggle. |
| `badge` | Status badge. |
| `button` | Button with variants and sizes, built on `cva`. |
| `card` | Card with header, content and footer. |
| `checkbox` | Native checkbox with kitr styling. |
| `data-table` | TanStack Table with sorting, pagination and URL-bound state via [table](/packages/table). |
| `dialog` | Modal dialog on the native `<dialog>` element. |
| `empty-state` | Centered empty state with title, description and action. |
| `form` | Styled `FormField`, `FormMessage` and `SubmitButton` over [forms](/packages/forms). |
| `icon` | Hugeicons in the stroke-rounded style. |
| `input`, `label`, `select`, `textarea` | Form controls. |
| `page-header` | Title, description and actions row for a page. |
| `skeleton` | Loading placeholder. |
| `sonner` | Toasts with sonner, themed by `kitr/theme`. |
| `theme-toggle` | Light and dark toggle using `useTheme`. |
| `list-page` | A list route: page header, data table bound to search params, empty state. Writes a page, not a component. |
| `sign-in-page` | A sign-in route using [forms](/packages/forms). Writes a page, not a component. |

To use your company's registry, set `registry` in `config/theme.ts`, pass `--registry`, or set `KITR_REGISTRY`. A registry is any URL or directory that serves `registry.json` and one `<name>.json` per component in the shadcn format.

## Use icons

Icons are [Hugeicons](https://hugeicons.com) in the stroke-rounded style: round caps, round joins, soft corners, drawn in `currentColor`. `kitr ui add icon` (every kit that includes theme has it) gives you `<Icon>`:

```tsx
// app/features/projects/add-project-button.tsx
import { Add01Icon } from '@hugeicons/core-free-icons'
import { Button } from '#components/ui/button'
import { Icon } from '#components/ui/icon'

export function AddProjectButton() {
  return (
    <Button>
      <Icon icon={Add01Icon} size={18} /> New project
    </Button>
  )
}
```

The registry components, the kit pages and the devtools overlay all draw from this set. Use one icon set across the app; don't mix in emoji or text glyphs as icons.

## Change the storage key or attribute

Two apps on one domain, such as `app.acme.com` and `admin.acme.com` sharing cookies, need different keys. Set them in config and pass the same values to the script:

```ts
// config/theme.ts
import { defineConfig } from 'kitr/theme'

export default defineConfig({
  default: 'system',
  storageKey: 'acme-admin-theme',
  attribute: 'data-mode',
  colors: { light: '#ffffff', dark: '#0a0a0a' },
  componentsDir: 'app/components/ui',
})
```

```tsx
// app/routes/__root.tsx (inside <head>)
<ThemeScript storageKey="acme-admin-theme" attribute="data-mode" />
```

With a different `attribute`, `kitr/theme/styles.css` no longer switches to dark, because its dark block targets `[data-theme="dark"]`. Copy the dark values into your own `[data-mode="dark"]` block in `app/styles/tokens.css`, or keep the default attribute.

## Use ThemeProvider on its own

The theme provider in `kitrrc.ts` renders `ThemeProvider` with your config. Outside a kitr app, such as in a Storybook or an embedded widget, render it yourself:

```tsx
// app/widget/main.tsx
import { ThemeProvider } from 'kitr/theme'
import { createRoot } from 'react-dom/client'
import { InvoiceStatus } from '../features/invoices/invoice-status'

createRoot(document.getElementById('acme-widget')!).render(
  <ThemeProvider defaultTheme="dark" storageKey="acme-widget-theme" colors={{ dark: '#0b1020' }}>
    <InvoiceStatus status="paid" />
  </ThemeProvider>,
)
```

| Prop | Default | Description |
| --- | --- | --- |
| `defaultTheme` | `'system'` | The theme before the user picks one. |
| `storageKey` | `'kitr-theme'` | The `localStorage` key and cookie name. |
| `attribute` | `'data-theme'` | The attribute set on `<html>`. |
| `initialResolved` | `'light'` | `resolved` before the first effect runs, for example from `themeFromCookie`, so the first render matches the server. |
| `colors` | none | `<meta name="theme-color">` per resolved theme. |

Don't render a second `ThemeProvider` inside a kitr app. The provider already wraps the tree, and a nested one keeps its own state, so its `toggle` would not change what the rest of the app reads.

## Errors

| Error | When | What to do |
| --- | --- | --- |
| `[kitr/theme] useTheme() must be used inside <ThemeProvider>.` | A component called `useTheme` with no theme provider above it. | Add the theme provider with `kitr add theme`, or render inside `ThemeProvider`. In tests, boot an app with `themeProvider`. |
| `Component "<name>" not found at <registry> (404)` | `kitr ui add` asked the registry for a component it does not have. | Check the name with `kitr ui list`, or the `registry` setting. |
| `Component "<name>" not found in <dir>` | The same, for a registry that is a local directory. | Check the directory has `<name>.json`. |
| No error: the file is kept | `kitr ui add` found the component file already there. It keeps yours and still reports the component as added. | Pass `--overwrite` to replace it with the registry's version. |

## Commands

| Command | What it does |
| --- | --- |
| `kitr ui add <names...>` | Copies components and their registry dependencies into `componentsDir`, and installs the npm packages they need. Flags: `--registry <url or dir>`, `--overwrite`, `--no-install`. |
| `kitr ui list` | Lists the components in the registry with a one-line description. Flag: `--registry`. |
| `kitr css:types` | Writes a typed `.d.ts` next to every `*.module.css` under `app`. Flags: `--dir <dir>`, `--check` to fail on stale files instead of writing. |

```sh
kitr ui add theme-toggle
```

This writes `app/components/ui/theme-toggle.tsx`, `app/components/ui/button.tsx` and `app/components/ui/icon.tsx`, and installs `class-variance-authority`, `@hugeicons/react` and `@hugeicons/core-free-icons`:

```tsx
// app/components/ui/theme-toggle.tsx
import { Moon02Icon, Sun03Icon } from '@hugeicons/core-free-icons'
import { useTheme } from 'kitr/theme'
import { Button } from '#components/ui/button'
import { Icon } from '#components/ui/icon'

export function ThemeToggle() {
  const { resolved, toggle } = useTheme()
  return (
    <Button
      variant="ghost"
      size="icon"
      onClick={toggle}
      aria-label={`Switch to ${resolved === 'dark' ? 'light' : 'dark'} theme`}
    >
      <Icon icon={resolved === 'dark' ? Sun03Icon : Moon02Icon} size={18} />
    </Button>
  )
}
```

```sh
kitr ui list
```

```
  app-shell        Sidebar + top bar layout with navigation links, user menu slot and theme toggle.
  badge            Status badge.
  button           Button with variants and sizes, built on cva.
  ...
  list-page        A list route: page header, data table bound to URL search params, empty state.  (page)
```

## Testing

In a test, boot an app with the theme provider and render with `renderWithKitr` from [testing](/packages/testing). Config goes in through `createTestApp`:

```tsx
// app/components/theme-button.test.tsx
import themeProvider from 'kitr/theme/provider'
import { createTestApp, renderWithKitr } from 'kitr/testing/react'
import { act } from '@testing-library/react'
import { describe, expect, it } from 'vitest'
import { ThemeButton } from './theme-button'

describe('ThemeButton', () => {
  it('switches Ada to dark mode and remembers it', async () => {
    const app = await createTestApp({
      providers: [themeProvider],
      config: { theme: { default: 'light' } },
    })
    const screen = renderWithKitr(<ThemeButton />, { app })

    const button = screen.getByRole('button', { name: 'Switch to dark' })
    await act(async () => button.click())

    expect(document.documentElement.getAttribute('data-theme')).toBe('dark')
    expect(localStorage.getItem('kitr-theme')).toBe('dark')
    expect(document.cookie).toContain('kitr-theme=dark')
    expect(screen.getByRole('button', { name: 'Switch to light' })).toBeTruthy()
  })
})
```

The theme is saved to `localStorage` and a cookie, which the test DOM keeps between tests. Clear them in an `afterEach` so one test's choice does not leak into the next:

```ts
// test/setup.ts
import { afterEach } from 'vitest'

afterEach(() => {
  localStorage.clear()
  document.cookie = 'kitr-theme=; max-age=0; path=/'
  document.documentElement.removeAttribute('data-theme')
})
```

To test what a component does in dark mode without clicking, save the choice before rendering: `localStorage.setItem('kitr-theme', 'dark')`. The provider reads it on mount.

For `system`, the provider asks `window.matchMedia('(prefers-color-scheme: dark)')`. Replace it to control the OS setting:

```ts
// test/dark-system.ts
import { vi } from 'vitest'

export function prefersDark(dark: boolean) {
  window.matchMedia = vi.fn(() => ({
    matches: dark,
    addEventListener: () => {},
    removeEventListener: () => {},
  })) as unknown as typeof window.matchMedia
}
```

Toasts need no fake. Without sonner they log, so spy on the console, or install your own implementation and assert on it:

```ts
// app/features/invoices/send-invoice.test.ts
import { setToastImplementation, toastError } from 'kitr/theme'
import { afterEach, expect, it, vi } from 'vitest'

afterEach(() => setToastImplementation(null))

it('shows the error message from a failed payment', () => {
  const shown = Object.assign(vi.fn(), {
    success: vi.fn(),
    error: vi.fn(),
    info: vi.fn(),
    warning: vi.fn(),
    promise: vi.fn(),
  })
  setToastImplementation(shown)

  toastError(new Error('Payment declined'))

  expect(shown.error).toHaveBeenCalledWith('Payment declined', undefined)
})
```

## Next steps

- [API reference](/packages/theme/api): every export of `kitr/theme`, `kitr/theme/provider` and `kitr/theme/server`.
- [Tailwind](/packages/tailwind): the same tokens as utility classes, and `cn()`.
- [Router](/packages/router): the root route where `<ThemeScript />` and the stylesheet go.
- [sonner](https://sonner.emilkowal.ski): toast options such as `description`, `action` and `duration`.
- [shadcn/ui](https://ui.shadcn.com/docs/registry): the registry format `kitr ui add` reads.


# Updater API

Source: https://kitr.dev/packages/updater/api

Every export of `kitr/updater`, `kitr/updater/react`, `kitr/updater/provider`, read from the published type definitions. The [guide](/packages/updater) shows them in use.

## kitr/updater

### createMemoryUpdaterDriver

```ts
function createMemoryUpdaterDriver(options?: {
  version?: string;
  next?: UpdateInfo | null;
}): {
  name: string;
  next: UpdateInfo | null;
  applied: UpdateInfo[];
  check: () => Promise<UpdateInfo | null>;
  apply: (onProgress?: (f: number) => void) => Promise<void>;
  onAvailable(listener: (info: UpdateInfo) => void): () => void;
  announce(info: UpdateInfo): void;
  currentVersion: () => Promise<string>;
};
```

For tests and the server: set `next` to simulate an available update.

### createServiceWorkerUpdaterDriver

```ts
function createServiceWorkerUpdaterDriver(options?: {
  version?: string;
}): UpdaterDriver;
```

Service-worker driver: an update is "available" when a new worker is waiting; applying tells it
to skip waiting and reloads. `version` is the running build; the update is reported as `<version>+`.

### createUpdater

```ts
function createUpdater(config?: UpdaterConfig, app?: KitrApp): Updater;
```

Build the `updater` service. The driver is `config.driver`, else the one registered on `app`, else
the service-worker driver in a browser. Starts the `interval` checks and the driver listener.

### useUpdater

```ts
function useUpdater(app: KitrApp): Updater;
```

The app's `updater` service, outside React. Same as `app.container.use('updater')`.

### defineConfig

```ts
const defineConfig: <const C extends UpdaterConfig>(config: C) => C;
```

Types `config/updater.ts`. Returns the object unchanged.

### UpdateInfo

```ts
interface UpdateInfo {
  /** Its version label, such as `2.4.0` (`new` from the service-worker driver without a version). */
  version: string;
  /** Release notes to show next to the update. */
  notes?: string;
  /** Release date, as the driver reports it. */
  date?: string;
  /** Bytes, when the driver knows. */
  size?: number;
}
```

A version the driver found.

### Updater

```ts
interface Updater {
  /** The active driver. */
  readonly driver: UpdaterDriver;
  /** The current snapshot. */
  readonly state: UpdaterState;
  /** Look for an update. Never throws: failures set `status: 'error'` and resolve to null. */
  check(): Promise<UpdateInfo | null>;
  /** Install the update found. Runs once however often it is called; failures set `status: 'error'`. */
  apply(): Promise<void>;
  /** Hide the prompt until the next update. */
  dismiss(): void;
  /** Call `listener` after every state change; returns an unsubscribe function. */
  subscribe(listener: () => void): () => void;
  /** Stop the interval and listeners. */
  stop(): void;
}
```

The `updater` service: check, apply and dismiss updates, and subscribe to the state.

### UpdaterConfig

```ts
interface UpdaterConfig {
  /** Replace the driver the service would pick (tests, custom shells). */
  driver?: UpdaterDriver;
  /** Re-check every N milliseconds while the app is open. Default: none (check at boot only). */
  interval?: number;
  /** Check as soon as the app boots. Default true. */
  checkOnBoot?: boolean;
  /** Apply as soon as an update is ready, without asking. Default false. */
  auto?: boolean;
}
```

Options for `config/updater.ts` and `createUpdater()`.

### UpdaterDriver

```ts
interface UpdaterDriver {
  /** Shown in devtools, such as `service-worker` or `memory`. */
  name: string;
  /** Look for a newer version. Resolves to the update or null when current. */
  check(): Promise<UpdateInfo | null>;
  /** Download (when needed) and install. Usually restarts or reloads the app. */
  apply(onProgress?: (fraction: number) => void): Promise<void>;
  /** Called by drivers that learn about updates on their own (service worker, background download). */
  onAvailable?(listener: (info: UpdateInfo) => void): () => void;
  /** Current app version, when known. */
  currentVersion?(): Promise<string>;
}
```

What a platform implements to find and install new versions.

### UpdaterState

```ts
interface UpdaterState {
  /** Where the flow is. */
  status: UpdateStatus;
  /** The update found, or null. */
  update: UpdateInfo | null;
  /** 0 to 1 while downloading. */
  progress: number;
  /** Why the last check or apply failed. Cleared by the next check. */
  error: Error | null;
  /** The running version, once the driver reports it. */
  currentVersion: string | null;
}
```

A snapshot of the updater, replaced on every change.

### UpdateStatus

```ts
/** Where the update flow is: `idle → checking → available → downloading → ready`, or `up-to-date` / `error`. */
type UpdateStatus = 'idle' | 'checking' | 'available' | 'downloading' | 'ready' | 'up-to-date' | 'error';
```

Where the update flow is: `idle → checking → available → downloading → ready`, or `up-to-date` / `error`.

## kitr/updater/react

### useUpdate

```ts
function useUpdate(): {
  available: boolean;
  check: () => Promise<UpdateInfo | null>;
  apply: () => Promise<void>;
  dismiss: () => void;
  status: UpdateStatus;
  update: UpdateInfo | null;
  progress: number;
  error: Error | null;
  currentVersion: string | null;
};
```

`{ status, update, progress, check, apply, dismiss }` for an "update ready" banner.
Hydration-safe: the server and first render see `idle`.

### useUpdater

```ts
function useUpdater(): Updater;
```

The app's `updater` service in a component. Only bound in the browser.

## kitr/updater/provider

### updaterProvider

```ts
const updaterProvider: import("@kitr/core").KitrProvider;
```

Binds `updater` to the platform updater (`updater` capability) or the service-worker driver,
checks at boot and on the configured interval, and stops at shutdown.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Updater

Source: https://kitr.dev/packages/updater

You ship a fix, but Ada keeps a tab on `app.acme.com` open all week and never reloads it. Installed apps are worse: they run the old version until someone thinks to update. `kitr/updater` notices when a new version is ready, tells people with a banner, and updates the app in place when they click it.

It is one `check()` and `apply()` flow with one status, whatever does the updating. In the browser the driver watches the [service worker](https://developer.mozilla.org/docs/Web/API/Service_Worker_API) that the [Web](/packages/web) platform's `pwa` option builds with [vite-plugin-pwa](https://vite-pwa-org.netlify.app/); applying activates the new worker and reloads. Desktop and mobile shells plug in their own updater as a driver. kitr adds the status machine, periodic checks, "remind me later", a React hook, a ready-made banner and a memory driver for tests.

It runs in the browser only. On the server the provider binds nothing. To keep data fresh between versions, use [Query](/packages/query); this package is about the app's own code.

This guide follows Acme's orders app: version 2.4.0 ships, Ada sees "Version 2.4.0 is ready", and one click moves her to it without losing her place.

## Install

```sh
kitr add updater
```

What `kitr add` does:

- Adds [Platform](/packages/platform) first when the project does not have it yet, because `updater` requires `platform`. The `desktop` and `mobile` kits already include it.
- Installs `@kitr/updater`.
- Adds `() => import('@kitr/updater/provider')` to `providers` in `kitrrc.ts`.
- Adds `@kitr/updater` to `packages` in `kitrrc.ts`.
- Writes `config/updater.ts` (shown under [Configure](#configure)).
- Writes `app/components/update-banner.tsx`, a banner that stays hidden until an update is ready (shown under [Show your first update banner](#show-your-first-update-banner)).
- Adds a `## kitr: updater` section to `AGENTS.md`: `useUpdate()` from `kitr/updater/react` drives the banner, which is mounted once in the root layout; status runs idle, checking, available, downloading, ready; the web driver watches the service worker and desktop and mobile packages register theirs.

It adds no environment variables or scripts. `kitr add updater` asks no questions, and no kit includes it. It is a client package, so a server-only project skips it with a warning. To preview the changes:

```sh
kitr add updater --dry-run
```

`kitr remove updater` removes the provider, the `packages` entry, the dependency, the `AGENTS.md` section and `config/updater.ts`. It leaves `app/components/update-banner.tsx` because you may have edited it, and lists the files that still import `kitr/updater`.

## Configure

`kitr add` writes this file:

```ts
// config/updater.ts
import { defineConfig } from 'kitr/updater'

export default defineConfig({
  checkOnBoot: true,
  interval: 60 * 60 * 1000, // look again every hour while the app is open
  auto: false, // true applies as soon as an update is ready, without asking
})
```

| Option | Default | Description |
| --- | --- | --- |
| `checkOnBoot` | `true` | Check once as the app starts. |
| `interval` | none | Check again every this many milliseconds while the app is open. Without it the app checks at start only. The generated file sets one hour. |
| `auto` | `false` | Apply as soon as an update is found, without asking. |
| `driver` | registered, else the service-worker driver | An `UpdaterDriver` that replaces the one the service would pick. For tests and custom shells. |

The service picks its driver in this order: `driver` from the config, a driver a provider registered under `updater`, then the service-worker driver in a browser. The defaults in the table are what you get without a config file; the file `kitr add` writes only adds the hourly `interval`.

For the browser to have something to update, turn on the service worker in the web platform. `registerType: 'prompt'` is the default and is what the updater expects: the new worker waits until you apply it.

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  // ...
  platforms: {
    site: web({ mode: 'spa', pwa: true }),
  },
})
```

## Show your first update banner

`kitr add` writes this component:

```tsx
// app/components/update-banner.tsx
import { useUpdate } from 'kitr/updater/react'

/** Mount once in the root layout. Hidden until the updater has something ready. */
export function UpdateBanner() {
  const { available, update, status, progress, apply, dismiss } = useUpdate()
  if (!available) return null
  return (
    <div role="status" className="fixed inset-x-0 bottom-0 flex items-center justify-center gap-3 bg-foreground p-3 text-sm text-background">
      <span>Version {update?.version} is ready.</span>
      <button type="button" className="rounded-md bg-background px-3 py-1 text-foreground" onClick={apply} disabled={status === 'downloading'}>
        {status === 'downloading' ? `Updating ${Math.round(progress * 100)}%` : 'Restart to update'}
      </button>
      <button type="button" className="underline" onClick={dismiss}>
        Later
      </button>
    </div>
  )
}
```

Mount it once, in the root route:

```tsx
// app/routes/__root.tsx
import { createRootRoute, Outlet } from 'kitr/router'
import { UpdateBanner } from '#app/components/update-banner'

export const Route = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <UpdateBanner />
    </>
  ),
})
```

Deploy a new build while Ada has the app open. Within the hour (or at her next visit) a bar appears at the bottom: "Version new is ready. **Restart to update** · Later". She clicks **Restart to update**, the page reloads on the new build, and the bar is gone. The service-worker driver does not know version numbers, so it reports `new` until you give it one; see [Show version numbers on the web](#show-version-numbers-on-the-web).

The service only exists in the browser. In an app whose web platform renders on the server (`mode: 'ssr'`), wrap the banner in `ClientOnly` from `kitr/router`, so the server render does not ask for it:

```tsx
// app/routes/__root.tsx
import { ClientOnly, createRootRoute, Outlet } from 'kitr/router'
import { UpdateBanner } from '#app/components/update-banner'

export const Route = createRootRoute({
  component: () => (
    <>
      <Outlet />
      <ClientOnly>
        <UpdateBanner />
      </ClientOnly>
    </>
  ),
})
```

Without it, the server render fails with `[kitr] No binding named "updater". Did you add the package that provides it?`.

## Follow the update status

`useUpdate()` returns the updater's state plus three actions:

| Field | Type | Description |
| --- | --- | --- |
| `status` | `UpdateStatus` | Where the flow is; see below. |
| `available` | `boolean` | `true` while `status` is `available` or `ready`. Show the banner on this. |
| `update` | `UpdateInfo \| null` | `{ version, notes?, date?, size? }` of the update found. |
| `progress` | `number` | `0` to `1` while downloading. |
| `error` | `Error \| null` | Why the last check or apply failed. |
| `currentVersion` | `string \| null` | The running version, when the driver knows it. |
| `check` | `() => Promise<UpdateInfo \| null>` | Look now. |
| `apply` | `() => Promise<void>` | Download and install. |
| `dismiss` | `() => void` | Hide this version. |

`status` moves through these values:

| Status | Meaning |
| --- | --- |
| `idle` | Nothing has happened yet. Also what the first render sees. |
| `checking` | A check is running. |
| `available` | An update was found and not applied. |
| `downloading` | `apply()` is running; `progress` moves. |
| `ready` | Installed. The driver usually restarts or reloads the app at this point. |
| `up-to-date` | The last check found nothing, or the person dismissed the update. |
| `error` | The last check or apply failed; `error` says why. |

A typical run is `idle → checking → available → downloading → ready`. A check during `downloading` or `ready` is skipped, so the hourly check never interrupts a download.

The hook reads the state with `useSyncExternalStore`, so a component re-renders on every change and nothing else.

## Check for updates by hand

Add a "Check for updates" item to a settings page. `check()` resolves to the update, or `null` when the app is current:

```tsx
// app/features/settings/check-for-updates.tsx
import { useUpdate } from 'kitr/updater/react'

export function CheckForUpdates() {
  const { status, check, currentVersion } = useUpdate()
  return (
    <section>
      <p>Acme Orders {currentVersion ?? ''}</p>
      <button type="button" onClick={check} disabled={status === 'checking'}>
        {status === 'checking' ? 'Checking…' : 'Check for updates'}
      </button>
      {status === 'up-to-date' && <p>You're on the latest version.</p>}
    </section>
  )
}
```

When something is found, `status` becomes `available` and the banner from the root layout shows it, so this page doesn't need its own "Update" button. A check never throws: a failure sets `status: 'error'` and `error`, and resolves to `null`.

## Apply an update

`apply()` downloads (where the driver needs to) and installs, moving `progress` from 0 to 1 on the way. Call it as many times as you like: while an apply is running or done, more calls do nothing, so a double click installs once.

```tsx
// app/features/settings/update-now.tsx
import { useUpdate } from 'kitr/updater/react'

export function UpdateNow() {
  const { status, update, progress, apply } = useUpdate()
  if (status !== 'available' && status !== 'downloading') return null
  return (
    <div>
      <p>Version {update?.version} is ready.</p>
      {update?.notes && <p>{update.notes}</p>}
      <progress value={progress} max={1} />
      <button type="button" onClick={apply} disabled={status === 'downloading'}>
        Install now
      </button>
    </div>
  )
}
```

What "install" means depends on the driver. The service-worker driver tells the waiting worker to take over, waits for it (up to two seconds) and reloads the page. A desktop driver typically downloads the installer and restarts the app. With no update found, `apply()` does nothing.

Applying reloads or restarts the app, so anything not saved is lost. Don't call `apply()` while someone is halfway through a form; let them choose the moment.

## Let people postpone an update

`dismiss()` hides the current update until a different version appears. It sets `status` to `up-to-date` and `update` to `null`:

```tsx
// app/features/settings/remind-me-later.tsx
import { useUpdate } from 'kitr/updater/react'

export function RemindMeLater() {
  const { update, dismiss } = useUpdate()
  if (!update) return null
  return (
    <button type="button" onClick={dismiss}>
      Remind me about {update.version} later
    </button>
  )
}
```

After Ada dismisses 2.4.0, the hourly check still finds 2.4.0 but keeps the banner hidden. When 2.4.1 ships, it appears again. The dismissal lives in memory, so a reload shows 2.4.0 again at the next check.

## Apply updates without asking

For a kiosk, a wall display or a dashboard nobody touches, set `auto: true`. Every update found by a check, or announced by the driver, is applied at once:

```ts
// config/updater.ts
import { defineConfig } from 'kitr/updater'

export default defineConfig({
  checkOnBoot: true,
  interval: 15 * 60 * 1000,
  auto: true,
})
```

On the web that means the page reloads by itself when a new build is deployed. Keep `auto: false` for anything people type into.

## Show version numbers on the web

A service worker does not know your version numbers, so the default web driver reports `update.version` as `'new'` and `currentVersion` as `'0.0.0'`. Give it your version and it reports `'2.3.0'` as the current one and `'2.3.0+'` for the waiting build. The `version` you pass is the build that is running; the service worker can't tell what the new one is called.

Set the driver yourself in the config, from the version Vite builds in:

```ts
// config/updater.ts
import { createServiceWorkerUpdaterDriver, defineConfig } from 'kitr/updater'
import { env } from '#app/env'

export default defineConfig({
  driver: createServiceWorkerUpdaterDriver({ version: env.VITE_APP_VERSION }),
  checkOnBoot: true,
  interval: 60 * 60 * 1000,
  auto: false,
})
```

Declare `VITE_APP_VERSION` in `app/env.ts` and set it in your build. [Offline](/packages/offline) adds the same variable when you install it. For a real version string in the banner, serve a small JSON file with each deploy and write a driver that reads it, as shown under [Extend](#extend).

The service-worker driver needs a registered worker. Without one, `check()` resolves to `null` and the status is `up-to-date`.

## Handle a failed update

Neither `check()` nor `apply()` throws. A failure sets `status: 'error'` and keeps the reason in `error`:

```tsx
// app/features/settings/update-error.tsx
import { useUpdate } from 'kitr/updater/react'

export function UpdateError() {
  const { status, error, check } = useUpdate()
  if (status !== 'error') return null
  return (
    <p role="alert">
      Couldn't update: {error?.message}.{' '}
      <button type="button" onClick={check}>
        Try again
      </button>
    </p>
  )
}
```

A later `check()` clears `error`. A non-`Error` rejection from the driver, such as `Promise.reject('offline')`, becomes `new Error('offline')`.

## Use it outside React

Outside components, read the service from the app's container. `useUpdater(app)` from `kitr/updater` does the same:

```ts
// app/features/settings/updates-on-focus.ts
import type { KitrApp } from 'kitr/app'
import { useUpdater } from 'kitr/updater'

export function checkWhenFocused(app: KitrApp) {
  const updater = useUpdater(app) // same as app.container.use('updater')
  const onFocus = () => void updater.check()
  window.addEventListener('focus', onFocus)
  const off = updater.subscribe(() => {
    if (updater.state.status === 'available') console.info('Update', updater.state.update?.version)
  })
  return () => {
    window.removeEventListener('focus', onFocus)
    off()
  }
}
```

`updater.state` is a fresh object after every change; `subscribe(listener)` calls `listener` with no arguments after each one and returns an unsubscribe function. `updater.stop()` ends the interval and the driver's listener; the provider calls it when the app shuts down. To build a service with no app, call `createUpdater(config)`. When the [Devtools](/packages/devtools) provider is installed, the service logs `available`, `applied` and failed checks and applies under `updater`.

## Where updates come from

| Where it runs | Driver | What `apply()` does |
| --- | --- | --- |
| Browser with `pwa` on | `createServiceWorkerUpdaterDriver()` | Activates the waiting worker and reloads the page. |
| Browser without a service worker | The same driver | Nothing to apply: every check is `up-to-date`. |
| Desktop and mobile shells | The service-worker driver, unless a provider registers one | Same as the browser. |
| Server | None; the provider binds nothing | Not available. |

Today [Desktop](/packages/desktop) and [Mobile](/packages/mobile) register only `platform` and `storage` drivers, not `updater`. To update an installed app, register a driver for your shell's updater, as shown under [Extend](#extend).

## Testing

`createMemoryUpdaterDriver({ version, next })` stands in for a real updater:

| Member | Description |
| --- | --- |
| `next` | The update the next `check()` finds, or `null`. Set it in the options or assign it later. |
| `applied` | Every update that `apply()` installed. |
| `announce(info)` | Simulates the driver finding an update on its own, as a service worker does. |
| `currentVersion()` | Resolves to `version`, default `'1.0.0'`. |

`apply()` reports progress `0.5` then `1`, records `next` in `applied` and clears `next`.

The provider only binds the updater in the browser environment, so create the test app with `environment: 'client'`:

```tsx
// app/components/update-banner.test.tsx
import { fireEvent, screen, waitFor } from '@testing-library/react'
import { createMemoryUpdaterDriver } from 'kitr/updater'
import { updaterProvider } from 'kitr/updater/provider'
import { createTestApp } from 'kitr/testing'
import { renderWithKitr } from 'kitr/testing/react'
import { describe, expect, it } from 'vitest'
import { UpdateBanner } from './update-banner'

async function setup(next: { version: string } | null) {
  const driver = createMemoryUpdaterDriver({ version: '2.3.0', next })
  const app = await createTestApp({
    environment: 'client',
    providers: [updaterProvider],
    config: { updater: { driver } },
  })
  return { app, driver }
}

describe('update banner', () => {
  it('shows the new version and installs it', async () => {
    const { app, driver } = await setup({ version: '2.4.0' })
    renderWithKitr(<UpdateBanner />, { app })
    await screen.findByText('Version 2.4.0 is ready.')
    fireEvent.click(screen.getByRole('button', { name: 'Restart to update' }))
    await waitFor(() => expect(driver.applied).toEqual([{ version: '2.4.0' }]))
    expect(app.container.use('updater').state).toMatchObject({ status: 'ready', progress: 1 })
  })

  it('stays hidden after Later until a newer version ships', async () => {
    const { app, driver } = await setup({ version: '2.4.0' })
    renderWithKitr(<UpdateBanner />, { app })
    fireEvent.click(await screen.findByRole('button', { name: 'Later' }))
    expect(screen.queryByRole('status')).toBeNull()
    driver.announce({ version: '2.4.0' })
    expect(screen.queryByRole('status')).toBeNull()
    driver.announce({ version: '2.4.1' })
    await screen.findByText('Version 2.4.1 is ready.')
  })

  it('renders nothing when the app is current', async () => {
    const { app } = await setup(null)
    renderWithKitr(<UpdateBanner />, { app })
    await waitFor(() => expect(app.container.use('updater').state.status).toBe('up-to-date'))
    expect(screen.queryByRole('status')).toBeNull()
  })
})
```

The provider checks at boot, so the banner finds `2.4.0` without a click. For code that takes the service directly, `createUpdater({ driver })` needs no app; call `updater.stop()` at the end of a test that sets `interval`.

## Extend

A driver implements `UpdaterDriver`:

```ts
interface UpdaterDriver {
  name: string
  check(): Promise<UpdateInfo | null> // null when current
  apply(onProgress?: (fraction: number) => void): Promise<void> // fraction 0..1
  onAvailable?(listener: (info: UpdateInfo) => void): () => void // for updates found in the background
  currentVersion?(): Promise<string>
}
```

The smallest useful driver for the web reads a `version.json` that each deploy writes next to `index.html` (for example `{ "version": "2.4.0", "notes": "Faster invoice search" }`) and reloads to apply:

```ts
// app/updater/version-file-driver.ts
import type { UpdateInfo, UpdaterDriver } from 'kitr/updater'

export function versionFileDriver(running: string): UpdaterDriver {
  return {
    name: 'version-file',
    async check() {
      const response = await fetch('/version.json', { cache: 'no-store' })
      if (!response.ok) throw new Error(`version.json: HTTP ${response.status}`)
      const latest = (await response.json()) as UpdateInfo
      return latest.version !== running ? latest : null
    },
    async apply(onProgress) {
      onProgress?.(1)
      location.reload()
    },
    currentVersion: async () => running,
  }
}
```

```ts
// config/updater.ts
import { defineConfig } from 'kitr/updater'
import { env } from '#app/env'
import { versionFileDriver } from '#app/updater/version-file-driver'

export default defineConfig({
  driver: versionFileDriver(env.VITE_APP_VERSION),
  checkOnBoot: true,
  interval: 60 * 60 * 1000,
  auto: false,
})
```

The banner now reads "Version 2.4.0 is ready." For an app without a service worker, this is the whole update flow.

For the Electron shell, run [electron-updater](https://www.electron.build/auto-update) in the main process and reach it over the IPC bridge the desktop platform sets up. Install it with `pnpm add electron-updater`, then handle three channels in main:

```ts
// platforms/app/main.ts
import { app, BrowserWindow, ipcMain } from 'electron'
import { autoUpdater } from 'electron-updater'
import { handleIpc } from 'kitr/desktop/electron-main'

autoUpdater.autoDownload = false

handleIpc<{
  'updater.check': () => { version: string; notes?: string } | null
  'updater.apply': () => void
}>(ipcMain, {
  'updater.check': async () => {
    const result = await autoUpdater.checkForUpdates()
    const info = result?.updateInfo
    if (!info || info.version === app.getVersion()) return null
    return { version: info.version, notes: typeof info.releaseNotes === 'string' ? info.releaseNotes : undefined }
  },
  'updater.apply': async () => {
    await autoUpdater.downloadUpdate()
    autoUpdater.quitAndInstall()
  },
})

autoUpdater.on('download-progress', (p) => {
  BrowserWindow.getAllWindows()[0]?.webContents.send('updater.progress', p.percent / 100)
})
// ...
```

```ts
// app/providers/electron_updater_provider.ts
import { defineProvider } from 'kitr/app'
import { createIpcClient } from 'kitr/desktop/electron'
import type { UpdaterDriver } from 'kitr/updater'

type UpdaterIpc = {
  'updater.check': () => { version: string; notes?: string } | null
  'updater.apply': () => void
}
const ipc = createIpcClient<UpdaterIpc, { 'updater.progress': (fraction: number) => void }>()

function electronUpdater(): UpdaterDriver {
  return {
    name: 'electron-updater',
    check: () => ipc.invoke('updater.check'),
    async apply(onProgress) {
      const off = ipc.on('updater.progress', (fraction) => onProgress?.(fraction))
      try {
        await ipc.invoke('updater.apply')
      } finally {
        off()
      }
    },
  }
}

export default defineProvider({
  name: 'electron-updater',
  register(app) {
    if (ipc.available) app.drivers.register('updater', electronUpdater(), { platform: 'desktop' })
  },
})
```

Create the provider with `kitr make:provider electron_updater` and add `() => import('#app/providers/electron_updater_provider')` to `providers` in `kitrrc.ts`. Inside the Electron app, the banner now shows the release version, the button shows download progress, and the app restarts on the new build. In the web build `ipc.available` is `false`, so the service-worker driver still applies.

A Tauri app does the same with [`@tauri-apps/plugin-updater`](https://v2.tauri.app/plugin/updater/): `check()` resolves to an update or `null`, and the update's `downloadAndInstall()` reports progress before you relaunch. The `UpdaterDriver` and `UpdateInfo` types are in the [API reference](/packages/updater/api).

## Next steps

- [API reference](/packages/updater/api)
- [Web](/packages/web): the `pwa` option that builds the service worker.
- [vite-plugin-pwa prompt for update](https://vite-pwa-org.netlify.app/guide/prompt-for-update): how the waiting worker is built.
- [electron-updater](https://www.electron.build/auto-update): publishing and signing desktop updates.
- [Desktop](/packages/desktop): the shell an installed-app driver plugs into.
- [Offline](/packages/offline): keep data across versions, dropped when `VITE_APP_VERSION` changes.


# Uploads API

Source: https://kitr.dev/packages/uploads/api

Every export of `kitr/uploads`, `kitr/uploads/react`, `kitr/uploads/server`, `kitr/uploads/provider`, read from the published type definitions. The [guide](/packages/uploads) shows them in use.

## kitr/uploads

### accepts

```ts
function accepts(type: string, name: string, accept?: string[]): boolean;
```

`image/*` matches `image/png`; exact types match themselves; `.pdf` matches by extension.

### checkFile

```ts
function checkFile(file: File, rules?: UploadRules): string | null;
```

Client-side check against the same rules the server enforces, so errors show before the request.

### formatBytes

```ts
function formatBytes(bytes: number): string;
```

Formats a byte count for people: `formatBytes(10 * 1024 * 1024)` is `'10.0 MB'`.

### upload

```ts
function upload(files: File | File[], options?: UploadOptions): Promise<UploadedFile[]>;
```

Upload one or more files with progress. XMLHttpRequest is the only browser API that reports
upload progress, so this is XHR with a promise around it; a fetch fallback runs elsewhere.

### UploadError

```ts
class UploadError extends Error {
  readonly status: number;
  readonly body?: unknown | undefined;
  constructor(message: string, status: number, body?: unknown | undefined);
}
```

What `upload()` rejects with: the server's message and HTTP `status` (0 for network errors and
cancels), and the parsed response `body`, which carries `fieldErrors` for rule violations.

### defineConfig

```ts
const defineConfig: <const C extends UploadsConfig>(config: C) => C;
```

Typed identity helper for `config/uploads.ts`.

### UploadedFile

```ts
interface UploadedFile {
  /** The random id the file was stored under: the first segment of `key`. */
  id: string;
  /** The original file name, as the browser sent it. */
  name: string;
  /** Size in bytes. */
  size: number;
  /** The MIME type the browser declared. Not sniffed from the bytes. */
  type: string;
  /** Where it can be fetched, when the driver serves files. */
  url?: string;
  /** The storage key the driver wrote. */
  key: string;
}
```

What the server returns for every stored file, and what the client resolves with.

### UploadOptions

```ts
interface UploadOptions {
  /** The endpoint, default `/api/uploads`. */
  url?: string;
  /** Form field name, default `file`. */
  field?: string;
  /** Extra fields sent with the file. */
  fields?: Record<string, string>;
  /** Extra request headers, such as a CSRF token. */
  headers?: Record<string, string>;
  /** Called as bytes go out, with `percent` from 0 to 100. Only the XHR path (browsers) reports progress. */
  onProgress?: (progress: {
    loaded: number;
    total: number;
    percent: number;
  }) => void;
  /** Aborts the upload; the promise rejects with `UploadError('Upload cancelled', 0)`. */
  signal?: AbortSignal;
  /** Sent with credentials (cookies). Default true. */
  credentials?: boolean;
}
```

Options for `upload()` and `useUpload()`: where to send, extra form fields and headers, progress and cancel.

### UploadRules

```ts
interface UploadRules {
  /** Bytes. Default 10 MiB. */
  maxSize?: number;
  /** Allowed MIME types or patterns such as `image/*`. Default: anything. */
  accept?: string[];
  /** Files per request. Default 1. */
  maxFiles?: number;
}
```

The size, type and count limits checked in the browser (`checkFile`, `useUpload`) and on the server (`receive`).

### UploadsConfig

```ts
interface UploadsConfig extends UploadRules {
  /** Where files go. Default: `storage/uploads` on disk (`createDiskUploadsDriver`). */
  driver?: unknown;
  /** Public URL prefix the driver answers under, e.g. `/uploads`. */
  publicPath?: string;
}
```

The shape of `config/uploads.ts`: the default rules plus where files are stored and served.

## kitr/uploads/react

### useUpload

```ts
function useUpload(options?: UploadOptions & UploadRules): {
  send: (input: FileList | File[] | File | null) => Promise<UploadedFile[]>;
  cancel: () => void | undefined;
  reset: () => void;
  files: UploadedFile[];
  progress: number;
  uploading: boolean;
  error: Error | null;
};
```

Upload with progress from a component:

```ts
const { send, progress, uploading, error } = useUpload({ accept: ['image/*'] })
<input type="file" onChange={(e) => send(e.target.files)} />
```
`send` checks every file against the rules first, then uploads; it resolves with the stored files and rethrows failures.

### UseUploadState

```ts
interface UseUploadState {
  /** The stored files from the last successful upload. */
  files: UploadedFile[];
  /** Percent sent, 0 to 100. */
  progress: number;
  /** True while a request is in flight. */
  uploading: boolean;
  /** The last failure: a plain `Error` from the client-side check, or an `UploadError` from the request. */
  error: Error | null;
}
```

The state `useUpload()` returns next to `send`, `cancel` and `reset`.

## kitr/uploads/server

### createDiskUploadsDriver

```ts
function createDiskUploadsDriver(options?: {
  dir?: string;
  publicPath?: string;
}): UploadsDriver;
```

Files under a directory (default `storage/uploads`), loaded lazily so the browser bundle never sees node:fs.

### createMemoryUploadsDriver

```ts
function createMemoryUploadsDriver(): UploadsDriver;
```

A driver that keeps files in a Map, for tests and demos. Everything is lost when the process exits.

### createUploads

```ts
function createUploads(config?: UploadsConfig): Uploads;
```

Creates the uploads service from a config: the driver (disk under `storage/uploads` by default)
and the default rules. The provider calls it with `config/uploads.ts`; call it yourself in tests.

### mountUploads

```ts
function mountUploads<S extends {
  h3: any;
  app: KitrApp;
}>(server: S, path?: string): S;
```

Mount `POST <path>` (receive) and `GET <path>/**` (serve) on a kitr server from `server/main.ts`.
The service is resolved per request, so this can run before the app has booted.

### servedFileHeaders

```ts
function servedFileHeaders(type: string, name?: string): Record<string, string>;
```

Headers for serving a stored file: never sniffed, sandboxed, and inline only when that is safe.

### useUploads

```ts
function useUploads(app: KitrApp): Uploads;
```

Returns the `uploads` service the provider bound, for a controller or job: `useUploads(ctx.app)`.

### StoredFile

```ts
interface StoredFile {
  key: string;
  name: string;
  size: number;
  type: string;
}
```

A stored file's key, original name, size and type.

### Uploads

```ts
interface Uploads {
  /** Read a multipart request, apply the rules and store the files. Throws KitrError on violation. */
  receive(event: H3Event, rules?: UploadRules & {
    field?: string;
  }): Promise<UploadedFile[]>;
  /** Store bytes directly (from a job, a migration). */
  store(file: {
    name: string;
    type: string;
    data: Uint8Array;
  }): Promise<UploadedFile>;
  /** Read a stored file's bytes and type, or `undefined`. */
  read(key: string): Promise<{
    data: Uint8Array;
    type: string;
  } | undefined>;
  /** Delete a stored file through the driver. */
  remove(key: string): Promise<void>;
  /** Mount `POST <path>` (receive) and `GET <path>/:key` (serve) on a kitr server. */
  mount<S extends {
    h3: any;
    app?: KitrApp;
  }>(server: S, path?: string): S;
  /** The driver files are stored with. */
  readonly driver: UploadsDriver;
}
```

The uploads service, as `createUploads` returns it and `useUploads(app)` reads it from the container.

### UploadsDriver

```ts
interface UploadsDriver {
  /** A short label, such as `disk` or `memory`. */
  name: string;
  /** Write the bytes under `key`, keeping `type` so `get` can return it. */
  put(key: string, data: Uint8Array, meta: {
    type: string;
    name: string;
  }): Promise<void>;
  /** Read a file back, or `undefined` when the key does not exist. */
  get(key: string): Promise<{
    data: Uint8Array;
    type: string;
  } | undefined>;
  /** Delete a file. Deleting a missing key is not an error. */
  delete(key: string): Promise<void>;
  /** A URL for the key, when files are served (CDN, signed URL, the kitr route). */
  url?(key: string): string | Promise<string>;
}
```

Where bytes go: disk, S3, R2, GCS. Keys are relative paths the driver owns.

## kitr/uploads/provider

### uploadsProvider

```ts
const uploadsProvider: import("@kitr/core").KitrProvider;
```

Binds `uploads` on the server from `config/uploads.ts`. The server module is loaded at boot so
the browser bundle of this provider never resolves node:fs.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Uploads

Source: https://kitr.dev/packages/uploads

Avatars, signed invoices, CSV imports: sooner or later an app takes files from people. `kitr/uploads` does the whole round trip. The browser checks size and type before sending and shows progress. The server checks again, stores the bytes through a driver (disk by default, or your own for S3 and R2) and answers with a file record you save in your database.

It runs on both sides: `kitr/uploads` and `kitr/uploads/react` in the browser, `kitr/uploads/server` on the [server](/packages/server). It handles files people send to your app. To read and write files on the user's own device, use [files](/packages/files) instead.

This guide follows Acme's order screen at `app.acme.com`, where Grace attaches the signed invoice PDF to order `ord_1042`.

## Install

```sh
kitr add uploads
```

What `kitr add` does:

- Adds the [server](/packages/server) package first if the project does not have it yet.
- Installs `@kitr/uploads` (you use it through `kitr/uploads`, `kitr/uploads/react` and `kitr/uploads/server`).
- Adds `() => import('@kitr/uploads/provider')` to `providers` in `kitrrc.ts`.
- Adds `'@kitr/uploads'` to `packages` in `kitrrc.ts`.
- Writes `config/uploads.ts` (shown under Configure). An existing file is left alone.
- Adds `import { mountUploads } from 'kitr/uploads/server'` and `mountUploads(server)` to `server/main.ts` when that file exists. This registers `POST /api/uploads` to receive files and `GET /api/uploads/**` to serve them.
- Regenerates `config/index.ts`, the config list the standalone server imports.
- Adds a `## kitr: uploads` section to `AGENTS.md`. In a React app it says to upload with `useUpload()` and check files with `checkFile(file, rules)`; in a server-only app it says to call `ctx.app.container.use('uploads').receive(event)` in a controller.

`kitr add uploads` asks no questions. Pass `--dry-run` to print the changes first, or `--no-install` to skip the package manager run. No kit includes uploads.

`kitr remove uploads` removes the provider, the package entry, the dependency, `config/uploads.ts` and the `AGENTS.md` section. It leaves the `mountUploads` line in `server/main.ts` and the files under `storage/uploads`.

## Configure

`kitr add uploads` writes this file:

```ts
// config/uploads.ts
import { defineConfig } from 'kitr/uploads'

export default defineConfig({
  maxSize: 10 * 1024 * 1024,
  accept: ['image/*', 'application/pdf'],
  // Files go to storage/uploads and are served under publicPath. Pass a driver for S3/R2.
  publicPath: '/uploads',
})
```

| Option | Default | Description |
| --- | --- | --- |
| `maxSize` | `10485760` (10 MiB) | Largest file in bytes. Checked per file. |
| `accept` | anything | Allowed types: exact MIME types (`application/pdf`), prefixes (`image/*`) or extensions (`.pdf`, case-insensitive). |
| `maxFiles` | `1` | Most files in one request. |
| `driver` | disk, under `storage/uploads` | Where bytes go. See Drivers. |
| `publicPath` | none | URL prefix for the `url` of each stored file, such as `/api/uploads`. Without it (and without a driver `url`), files have no `url`. |

Uploads adds no environment variables. The disk driver's directory is relative to the process's working directory.

### Match publicPath to the route

`mountUploads(server)` serves files under `/api/uploads`, but the generated config sets `publicPath: '/uploads'`. With that value, the `url` of a stored file points to `/uploads/<key>`, which nothing serves. Set `publicPath` to the mounted path so `url` works:

```ts
// config/uploads.ts
import { defineConfig } from 'kitr/uploads'

export default defineConfig({
  maxSize: 10 * 1024 * 1024,
  accept: ['image/png', 'image/jpeg', 'application/pdf'],
  publicPath: '/api/uploads',
})
```

### Raise the server's body limit

The [server](/packages/server) refuses any request body over `bodyLimit`, which defaults to 1 MiB, before uploads sees it. A 3 MB invoice gets `413 PAYLOAD_TOO_LARGE`, not the uploads size message. Set `bodyLimit` a little above `maxSize × maxFiles`, to leave room for the multipart framing:

```ts
// config/server.ts
import { defineConfig } from 'kitr/server'

export default defineConfig({
  healthPath: '/healthz',
  bodyLimit: 11 * 1024 * 1024,
})
```

## Upload your first file

With `kitr add uploads` done, the server already accepts files at `POST /api/uploads`. Set `publicPath: '/api/uploads'` as shown under Configure, so the returned `url` works. Then add a component that sends a file:

```tsx
// app/features/orders/invoice-upload.tsx
import { useUpload } from 'kitr/uploads/react'

export function InvoiceUpload() {
  const { send, progress, uploading, error, files } = useUpload({
    accept: ['application/pdf'],
    maxSize: 10 * 1024 * 1024,
  })
  return (
    <div>
      <input type="file" accept="application/pdf" onChange={(e) => send(e.target.files).catch(() => {})} />
      {uploading ? <progress value={progress} max={100} /> : null}
      {files[0] ? <a href={files[0].url}>{files[0].name}</a> : null}
      {error ? <p role="alert">{error.message}</p> : null}
    </div>
  )
}
```

Grace picks `invoice-1042.pdf`. The hook checks it against the rules, posts it as `multipart/form-data` to `/api/uploads`, and updates `progress` from 0 to 100 as the bytes go out. The server checks the rules again, writes the file to `storage/uploads/<id>/invoice-1042.pdf`, and answers:

```json
{
  "files": [
    {
      "id": "72eb7790-7c62-4c37-9167-d9989b7ac10f",
      "key": "72eb7790-7c62-4c37-9167-d9989b7ac10f/invoice-1042.pdf",
      "name": "invoice-1042.pdf",
      "size": 48213,
      "type": "application/pdf",
      "url": "/api/uploads/72eb7790-7c62-4c37-9167-d9989b7ac10f/invoice-1042.pdf"
    }
  ]
}
```

`files` in the hook holds that array, so the link appears. `send` also returns it. It rethrows failures, which is why the `onChange` above ends with `.catch(() => {})`: the hook already shows the error in `error`.

## Track progress and cancel

In a component, `useUpload(options)` returns the state and three functions:

| Field | Description |
| --- | --- |
| `send(input)` | Takes a `FileList`, an array of `File`, one `File` or `null`. Checks, uploads, resolves with the stored files. `null` or an empty list resolves with `[]`. |
| `cancel()` | Aborts the request in flight. `error` becomes `Upload cancelled`. |
| `reset()` | Clears `files`, `progress` and `error`. |
| `files` | The stored files from the last successful upload. |
| `progress` | Percent sent, 0 to 100. |
| `uploading` | `true` while the request is in flight. |
| `error` | The last failure, or `null`. |

A progress indicator with a cancel button:

```tsx
// app/features/orders/attachment-upload.tsx
import { formatBytes } from 'kitr/uploads'
import { useUpload } from 'kitr/uploads/react'

const MAX = 25 * 1024 * 1024

export function AttachmentUpload() {
  const upload = useUpload({ maxSize: MAX, maxFiles: 3 })
  return (
    <div>
      <input type="file" multiple onChange={(e) => upload.send(e.target.files).catch(() => {})} />
      <p>Up to 3 files, {formatBytes(MAX)} each.</p>
      {/* => "Up to 3 files, 25.0 MB each." */}
      {upload.uploading ? (
        <>
          <progress value={upload.progress} max={100} />
          <button type="button" onClick={upload.cancel}>Cancel</button>
        </>
      ) : null}
    </div>
  )
}
```

Calling `send` again while an upload runs aborts the first one. `maxFiles` in the hook's options is sent nowhere and checked nowhere in the browser; the server enforces it.

## Upload without React

`upload(files, options)` from `kitr/uploads` is the same request without the hook. Use it in a store, an action or plain script code:

```ts
// app/features/orders/attach-invoice.ts
import { upload, UploadError } from 'kitr/uploads'

export async function attachInvoice(orderId: string, file: File) {
  const controller = new AbortController()
  try {
    const [stored] = await upload(file, {
      url: `/api/orders/${orderId}/invoice`,
      field: 'invoice',
      fields: { orderId },
      headers: { 'x-csrf-token': document.querySelector<HTMLMetaElement>('meta[name=csrf]')?.content ?? '' },
      onProgress: ({ loaded, total, percent }) => console.log(`${loaded}/${total} (${percent}%)`),
      signal: controller.signal,
    })
    return stored
  } catch (error) {
    if (error instanceof UploadError) console.warn(error.status, error.message)
    throw error
  }
}
```

| Option | Default | Description |
| --- | --- | --- |
| `url` | `'/api/uploads'` | The endpoint to post to. |
| `field` | `'file'` | The form field the files go in. The server reads the same field. |
| `fields` | none | Extra form fields sent before the files. |
| `headers` | none | Extra request headers, such as a CSRF token. |
| `onProgress` | none | Called with `{ loaded, total, percent }` as bytes go out. |
| `signal` | none | An `AbortSignal` that cancels the upload. |
| `credentials` | `true` | Send cookies with the request. `false` omits them. |

In a browser, `upload` uses `XMLHttpRequest`, the only browser API that reports upload progress. Where there is no `XMLHttpRequest` (Node, a test), it uses `fetch` and `onProgress` is not called. It resolves with the response's `files` array, or with the body itself wrapped in an array when the endpoint returns one file record.

## Check a file before sending

`checkFile(file, rules)` runs the browser half of the rules and returns a message, or `null` when the file passes. `useUpload` calls it for you; call it yourself to show the problem as soon as a file is picked:

```ts
// app/features/orders/check-invoice.ts
import { checkFile } from 'kitr/uploads'

const scan = new File([new Uint8Array(12 * 1024 * 1024)], 'scan.png', { type: 'image/png' })

checkFile(scan, { maxSize: 10 * 1024 * 1024 })
// => 'scan.png is larger than 10.0 MB'
checkFile(new File(['png'], 'logo.png', { type: 'image/png' }), { accept: ['application/pdf'] })
// => 'logo.png is not an accepted type'
checkFile(new File(['%PDF-1.7'], 'invoice-1042.pdf', { type: 'application/pdf' }), { accept: ['.pdf'] })
// => null
```

`checkFile` uses a 10 MiB `maxSize` when you pass none, like the server. It does not check `maxFiles`. Import the rules from one place so both sides agree, as shown in Share rules between client and server.

`accepts(type, name, accept)` is the type test on its own, and `formatBytes(bytes)` formats sizes for hints:

```ts
// app/features/orders/accept-hint.ts
import { accepts, formatBytes } from 'kitr/uploads'

accepts('image/png', 'logo.png', ['image/*'])
// => true
accepts('application/octet-stream', 'Invoice.PDF', ['.pdf'])
// => true
accepts('application/pdf', 'invoice.pdf.exe', ['.pdf'])
// => false
formatBytes(2048)
// => '2 KB'
formatBytes(10 * 1024 * 1024)
// => '10.0 MB'
```

## Share rules between client and server

The browser check is for people; the server check is for safety. Keep both from drifting by putting the rules in one module that a component and a controller both import:

```ts
// app/features/orders/invoice-rules.ts
import type { UploadRules } from 'kitr/uploads'

export const invoiceRules: UploadRules = {
  maxSize: 10 * 1024 * 1024,
  accept: ['application/pdf', '.pdf'],
  maxFiles: 1,
}
```

```tsx
// app/features/orders/invoice-field.tsx
import { useUpload } from 'kitr/uploads/react'
import { invoiceRules } from './invoice-rules'

export function InvoiceField({ orderId }: { orderId: string }) {
  const { send, error } = useUpload({ ...invoiceRules, url: `/api/orders/${orderId}/invoice` })
  return (
    <label>
      Signed invoice
      <input type="file" accept=".pdf" onChange={(e) => send(e.target.files).catch(() => {})} />
      {error ? <span role="alert">{error.message}</span> : null}
    </label>
  )
}
```

The controller that receives it is in the next section.

> **Warning**
> Never rely on the browser check alone. Anyone can post to the endpoint directly, with any size and any declared type. The server's `receive` is the check that counts.

## Receive files in a controller

`mountUploads` gives you one general endpoint. For files that belong to something, such as an order's invoice, receive them in your own [api](/packages/api) controller. On the server, `useUploads(ctx.app)` returns the service the provider bound, and `receive(event, rules)` reads the multipart body, applies the rules and stores the files:

```ts
// server/controllers/order_invoices_controller.ts
import type { HttpContext } from 'kitr/api'
import { useUploads } from 'kitr/uploads/server'
import { invoiceRules } from '#app/features/orders/invoice-rules'

export default class OrderInvoicesController {
  async store({ app, event, params }: HttpContext<{ orderId: string }>) {
    const [invoice] = await useUploads(app).receive(event, { ...invoiceRules, field: 'file' })
    // ... save invoice.key and invoice.name on order params.orderId in your database
    return { files: [invoice] }
  }
}
```

```ts
// server/routes.ts
import { defineRoutes } from 'kitr/api'
import OrderInvoicesController from '#server/controllers/order_invoices_controller'

export const routes = defineRoutes((router) =>
  router.post('/api/orders/:orderId/invoice', [OrderInvoicesController, 'store']),
)
```

Rules passed to `receive` replace the config's rules one by one: `maxSize`, `accept`, `maxFiles`, and `field` (default `'file'`). Anything you leave out comes from `config/uploads.ts`. Every file is checked before the next is stored, so a batch can be partly stored when its second file breaks a rule; check sizes and types in the browser to make that rare.

When a rule fails, `receive` throws a `VALIDATION` error, and the response is:

```json
{
  "code": "VALIDATION",
  "message": "Validation failed",
  "status": 422,
  "fieldErrors": { "file": ["notes.txt is not an accepted type"] }
}
```

The `fieldErrors` key is the field name, so a [form](/packages/forms) can show it under the input with that name. Don't give the route a body schema in `static validation`: that reads the body as JSON or form data before `receive` can.

## Store the record in your database

`receive` and `store` return an `UploadedFile`. Save `key`, which is how you read or delete the file later, and `name` for display. Don't save `url`; build it from `key` when you render, so a later change of `publicPath` or driver does not break old rows.

| Field | Example | Description |
| --- | --- | --- |
| `id` | `'72eb7790-...'` | A random UUID, the first segment of `key`. |
| `key` | `'72eb7790-.../invoice-1042.pdf'` | The storage key: the id, a slash, and the name made safe. |
| `name` | `'invoice 1042.pdf'` | The original name, unchanged. Escape it when you render it. |
| `size` | `48213` | Bytes. |
| `type` | `'application/pdf'` | The type the browser declared. Not checked against the bytes. |
| `url` | `'/api/uploads/72eb.../invoice-1042.pdf'` | From the driver's `url(key)`, else `publicPath + key`, else absent. |

The safe name keeps letters, digits, `.`, `_` and `-`, turns slashes into `_` and anything else into `-`, and is cut to 120 characters. `../../etc/passwd` becomes `.._.._etc_passwd`, inside its own id folder.

## Store and read files from server code

On the server, `store` writes bytes you already have, such as a generated PDF or an import from another system. `read` and `remove` complete the set:

```ts
// server/jobs/archive_invoice.ts
import type { KitrApp } from 'kitr/app'
import { useUploads } from 'kitr/uploads/server'

export async function archiveInvoice(app: KitrApp, pdf: Uint8Array) {
  const uploads = useUploads(app)
  const stored = await uploads.store({ name: 'Q3 report.pdf', type: 'application/pdf', data: pdf })
  // => { id: '788c...', key: '788c.../Q3-report.pdf', name: 'Q3 report.pdf', size: 48213, type: 'application/pdf', url: '/api/uploads/788c.../Q3-report.pdf' }

  const file = await uploads.read(stored.key)
  // => { data: Uint8Array(48213), type: 'application/pdf' }

  await uploads.remove(stored.key)
  await uploads.read(stored.key)
  // => undefined
  return stored
}
```

`store` does not check the rules; they are for files people send. The provider binds `uploads` on the server only, so `useUploads` in browser code throws `[kitr] No binding named "uploads"`. In a controller, `ctx.app.container.use('uploads')` returns the same service.

## Serve files safely

`mountUploads(server)` answers `GET /api/uploads/<key>` with the stored bytes, the stored type as `content-type`, and a one-year immutable cache header. The type is whatever the uploader's browser declared.

> **Warning**
> A file served with its declared type runs in your site's origin. An `image/svg+xml` or `text/html` upload can carry a script, and `image/*` accepts SVG. With `mountUploads`, accept only exact safe types (`image/png`, `image/jpeg`, `application/pdf`), or serve files through your own route with `servedFileHeaders`, as below.

`servedFileHeaders(type, name)` from `kitr/uploads/server` returns headers that serve images, audio, video, PDF and plain text inline, and everything else as a download, with `nosniff` and a sandboxing content security policy:

```ts
// server/main.ts
import { createServer } from 'kitr/server'
import { mountRoutes } from 'kitr/api'
import { servedFileHeaders, useUploads } from 'kitr/uploads/server'
import { config } from '../config'
import rc from '../kitrrc'
import { routes } from './routes'

export const server = createServer({ providers: rc.providers, config })
mountRoutes(server, routes)

server.h3.post('/api/uploads', async (event) => ({ files: await useUploads(server.app).receive(event) }))
server.h3.get('/api/uploads/**', async (event) => {
  const key = decodeURIComponent(new URL(event.req.url).pathname.slice('/api/uploads/'.length))
  const file = await useUploads(server.app).read(key)
  if (!file) return new Response('Not found', { status: 404 })
  return new Response(file.data as BodyInit, { headers: servedFileHeaders(file.type, key.split('/').pop()) })
})
```

Use this in place of the `mountUploads(server)` line. For an HTML upload, the headers are:

```ts
// server/check_headers.ts
import { servedFileHeaders } from 'kitr/uploads/server'

servedFileHeaders('text/html', 'page.html')
// => {
//   'content-type': 'application/octet-stream',
//   'content-disposition': 'attachment; filename="page.html"',
//   'x-content-type-options': 'nosniff',
//   'content-security-policy': "default-src 'none'; img-src 'self'; media-src 'self'; sandbox",
//   'cache-control': 'public, max-age=31536000, immutable',
// }
```

`uploads.mount(server, path)` on a service from `createUploads` registers the same two routes with these headers already applied. See Use the service without the provider.

Every file under the route is public to anyone with its key. Keys contain a random UUID, so they cannot be guessed, but anyone you share a link with can pass it on. For private files, such as invoices, don't mount a public `GET`. Serve them from a controller that checks the user first, as below.

## Serve private files

Read the file in a controller that checks access, and answer with the safe headers:

```ts
// server/controllers/order_invoices_controller.ts
import type { HttpContext } from 'kitr/api'
import { KitrError } from 'kitr/app'
import { servedFileHeaders, useUploads } from 'kitr/uploads/server'

export default class OrderInvoicesController {
  async show({ app, params, locals }: HttpContext<{ orderId: string }>) {
    if (!locals.user) throw KitrError.unauthorized()
    // ... look up the order and its invoice key in your database, and check the user's team
    const key = '72eb7790-7c62-4c37-9167-d9989b7ac10f/invoice-1042.pdf'
    const file = await useUploads(app).read(key)
    if (!file) throw KitrError.notFound('Invoice')
    return new Response(file.data as BodyInit, {
      headers: { ...servedFileHeaders(file.type, 'invoice-1042.pdf'), 'cache-control': 'private, no-store' },
    })
  }
}
```

`locals.user` is set by the [auth](/packages/auth) middleware. Override `cache-control`, because the default lets shared caches keep the file for a year.

## Show field errors in a form

A server rejection reaches the browser as an `UploadError`. Its `status` is the HTTP status and its `body` is the parsed response, so field messages are at `body.fieldErrors`:

```tsx
// app/features/orders/invoice-error.tsx
import { UploadError } from 'kitr/uploads'

export function InvoiceError({ error }: { error: Error | null }) {
  if (!error) return null
  if (error instanceof UploadError && error.status === 422) {
    const fields = (error.body as { fieldErrors?: Record<string, string[]> }).fieldErrors
    return <p role="alert">{fields?.file?.[0] ?? error.message}</p>
  }
  if (error instanceof UploadError && error.status === 413) return <p role="alert">That file is too large.</p>
  return <p role="alert">{error.message}</p>
}
```

A failure of the browser check in `useUpload` is a plain `Error` with the `checkFile` message, not an `UploadError`, and no request is sent.

## Drivers

A driver decides where bytes live. Two ship with kitr; any other storage is a driver you write (see Extend).

| Driver | Import | Use it for |
| --- | --- | --- |
| Disk | `createDiskUploadsDriver` | The default. One server with a persistent disk. |
| Memory | `createMemoryUploadsDriver` | Tests and demos. Files vanish on restart. |
| S3, R2, GCS | your own `UploadsDriver` | Several servers, serverless hosts, a CDN. |

### Disk

The default when `driver` is not set. Nothing to install.

```ts
// config/uploads.ts
import { defineConfig } from 'kitr/uploads'
import { createDiskUploadsDriver } from 'kitr/uploads/server'

export default defineConfig({
  driver: createDiskUploadsDriver({ dir: '/var/lib/acme/uploads', publicPath: '/api/uploads' }),
  maxSize: 10 * 1024 * 1024,
  accept: ['image/png', 'image/jpeg', 'application/pdf'],
})
```

| Option | Default | Description |
| --- | --- | --- |
| `dir` | `'storage/uploads'` | Directory, relative to the working directory or absolute. Created on first write. |
| `publicPath` | none | Gives the driver a `url(key)` that returns `publicPath/key`. |

Each file is written next to a `<file>.meta.json` sidecar that keeps its type and name. Keys that resolve outside `dir`, or that name a sidecar, throw `FORBIDDEN` (`Bad upload key`). A file without a sidecar is read back as `application/octet-stream`. The disk driver loads `node:fs` only when it runs, so importing it in `config/uploads.ts` keeps it out of the browser bundle.

> **Warning**
> On hosts with an ephemeral filesystem (most containers, serverless platforms), files under `storage/uploads` are lost on every deploy or restart. Mount a persistent volume at `dir`, or use an object storage driver.

### Memory

```ts
// config/uploads.ts
import { defineConfig } from 'kitr/uploads'
import { createMemoryUploadsDriver } from 'kitr/uploads/server'

export default defineConfig({
  driver: createMemoryUploadsDriver(),
  publicPath: '/api/uploads',
})
```

The memory driver has no `url`, so `publicPath` builds the URLs. Use it in tests (see Testing).

## Use the service without the provider

`createUploads(config)` builds the service on its own. Use it when a driver imports a server-only SDK you don't want in `config/uploads.ts` (which a React app bundles for the browser too), or for a second set of rules with its own route:

```ts
// server/avatars.ts
import { createDiskUploadsDriver, createUploads } from 'kitr/uploads/server'

export const avatars = createUploads({
  driver: createDiskUploadsDriver({ dir: 'storage/avatars', publicPath: '/api/avatars' }),
  maxSize: 2 * 1024 * 1024,
  accept: ['image/png', 'image/jpeg', 'image/webp'],
})
```

```ts
// server/main.ts
import { createServer } from 'kitr/server'
import { config } from '../config'
import rc from '../kitrrc'
import { avatars } from './avatars'

export const server = createServer({ providers: rc.providers, config })
// POST /api/avatars receives, GET /api/avatars/** serves with servedFileHeaders.
avatars.mount(server, '/api/avatars')
```

`mount` receives with the service's own rules and serves with the safe headers. In components, point the hook at it: `useUpload({ url: '/api/avatars', accept: ['image/png', 'image/jpeg', 'image/webp'] })`.

## Errors

The server throws kitr errors, so they reach the browser in the usual JSON shape. `upload()` and `useUpload` turn any non-2xx response into an `UploadError`.

| Code / message | When | What to do |
| --- | --- | --- |
| `VALIDATION`, `Expected multipart/form-data` | The request is not a multipart form. | Send with `upload()` or a `FormData` body. |
| `VALIDATION`, `No file sent` | The form has no file in the expected field. | Match `field` on both sides (default `file`). |
| `VALIDATION`, `At most 1 file(s)` | More files than `maxFiles`. | Raise `maxFiles`, or send fewer. |
| `VALIDATION`, `invoice.pdf is larger than 10485760 bytes` | A file is over `maxSize`. | Show the limit with `formatBytes`. |
| `VALIDATION`, `notes.txt is not an accepted type` | A file fails `accept`. | Pick another file, or widen `accept`. |
| `PAYLOAD_TOO_LARGE` (413) | The whole body is over the server's `bodyLimit`. | Raise `bodyLimit` in `config/server.ts`. |
| `NOT_FOUND`, `File not found` | `GET` for a key that does not exist. | Check the stored key. |
| `FORBIDDEN`, `Bad upload key` | Disk driver: the key leaves `dir` or names a sidecar. | Use keys from `store` or `receive` only. |
| `UploadError`, status `0`, `Network error during upload` | The request never completed. | Retry when online. |
| `UploadError`, status `0`, `Upload cancelled` | `cancel()` or the `signal` aborted it. | Nothing; the user cancelled. |
| `UploadError`, `Upload failed (502)` | A non-JSON error response, such as a proxy page. | Check the proxy or server logs. |

## Testing

Use the memory driver and call the server directly with `server.fetch`; no port, no disk. This test posts Grace's invoice through the real route and checks the rules:

```ts
// test/uploads.test.ts
import { silentLogger } from 'kitr/logger'
import { createServer } from 'kitr/server'
import { createMemoryUploadsDriver, createUploads } from 'kitr/uploads/server'
import { describe, expect, it } from 'vitest'

function setup() {
  const uploads = createUploads({
    driver: createMemoryUploadsDriver(),
    accept: ['application/pdf'],
    maxSize: 1024,
    publicPath: '/api/uploads',
  })
  const server = createServer({ logger: silentLogger })
  uploads.mount(server)
  return { uploads, server }
}

function post(server: { fetch(request: Request): Promise<Response> }, file: File) {
  const form = new FormData()
  form.append('file', file)
  return server.fetch(new Request('http://acme.test/api/uploads', { method: 'POST', body: form }))
}

describe('invoice uploads', () => {
  it('stores a PDF and serves it back', async () => {
    const { uploads, server } = setup()
    const res = await post(server, new File(['%PDF-1.7'], 'invoice 1042.pdf', { type: 'application/pdf' }))
    expect(res.status).toBe(200)

    const { files } = (await res.json()) as { files: Array<{ key: string; name: string; size: number; url: string }> }
    expect(files[0]).toMatchObject({ name: 'invoice 1042.pdf', size: 8 })
    expect(files[0]!.key).toMatch(/\/invoice-1042\.pdf$/)
    expect(files[0]!.url).toBe(`/api/uploads/${files[0]!.key}`)

    const served = await server.fetch(new Request(`http://acme.test${files[0]!.url}`))
    expect(served.headers.get('content-type')).toBe('application/pdf')
    expect(await served.text()).toBe('%PDF-1.7')
    expect(await uploads.read(files[0]!.key)).toBeDefined()
  })

  it('rejects a file of the wrong type with a field error', async () => {
    const { server } = setup()
    const res = await post(server, new File(['hi'], 'notes.txt', { type: 'text/plain' }))
    expect(res.status).toBe(422)
    expect(await res.json()).toMatchObject({
      code: 'VALIDATION',
      fieldErrors: { file: ['notes.txt is not an accepted type'] },
    })
  })
})
```

To test code that calls `useUploads(app)`, boot an app with the provider and a memory driver from [testing](/packages/testing):

```ts
// server/jobs/archive_invoice.test.ts
import { createTestApp } from 'kitr/testing'
import { uploadsProvider } from 'kitr/uploads/provider'
import { createMemoryUploadsDriver, useUploads } from 'kitr/uploads/server'
import { expect, it } from 'vitest'

it('stores the generated report', async () => {
  const app = await createTestApp({
    providers: [uploadsProvider],
    config: { uploads: { driver: createMemoryUploadsDriver() } },
  })
  const stored = await useUploads(app).store({
    name: 'Q3 report.pdf',
    type: 'application/pdf',
    data: new TextEncoder().encode('%PDF'),
  })
  expect(stored).toMatchObject({ name: 'Q3 report.pdf', size: 4 })
  expect(stored.key).toMatch(/\/Q3-report\.pdf$/)
})
```

On the client, `upload()` falls back to `fetch` when there is no `XMLHttpRequest`, so a Node test can replace `globalThis.fetch` with `(url, init) => server.fetch(new Request('http://acme.test' + url, init))` and call `upload()` against the same server.

## Extend

Any storage is a driver: an object with `put`, `get`, `delete` and, optionally, `url`. Keys are relative paths such as `72eb.../invoice-1042.pdf` that the driver owns.

```ts
// node_modules/@kitr/uploads/dist/server.d.ts (excerpt)
export interface UploadsDriver {
  name: string
  put(key: string, data: Uint8Array, meta: { type: string; name: string }): Promise<void>
  get(key: string): Promise<{ data: Uint8Array; type: string } | undefined>
  delete(key: string): Promise<void>
  url?(key: string): string | Promise<string>
}
```

An S3 driver with the [AWS SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/). It also works with Cloudflare R2 and other S3-compatible stores through `endpoint`:

```sh
pnpm add @aws-sdk/client-s3
```

```ts
// server/uploads/s3-driver.ts
import { DeleteObjectCommand, GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3'
import type { UploadsDriver } from 'kitr/uploads/server'

export function createS3UploadsDriver(options: { bucket: string; endpoint?: string; publicUrl?: string }): UploadsDriver {
  const s3 = new S3Client({ endpoint: options.endpoint, region: process.env.AWS_REGION ?? 'auto' })
  return {
    name: 's3',
    async put(key, data, meta) {
      await s3.send(new PutObjectCommand({ Bucket: options.bucket, Key: key, Body: data, ContentType: meta.type }))
    },
    async get(key) {
      try {
        const object = await s3.send(new GetObjectCommand({ Bucket: options.bucket, Key: key }))
        const data = await object.Body!.transformToByteArray()
        return { data, type: object.ContentType ?? 'application/octet-stream' }
      } catch (error) {
        if ((error as { name?: string }).name === 'NoSuchKey') return undefined
        throw error
      }
    },
    async delete(key) {
      await s3.send(new DeleteObjectCommand({ Bucket: options.bucket, Key: key }))
    },
    url: options.publicUrl ? (key) => `${options.publicUrl}/${key}` : undefined,
  }
}
```

Register it with a service created in server code, so the SDK stays out of the browser bundle:

```ts
// server/uploads/index.ts
import { createUploads } from 'kitr/uploads/server'
import { createS3UploadsDriver } from './s3-driver'

export const uploads = createUploads({
  driver: createS3UploadsDriver({
    bucket: 'acme-uploads',
    endpoint: process.env.S3_ENDPOINT,
    publicUrl: 'https://files.acme.com',
  }),
  maxSize: 10 * 1024 * 1024,
  accept: ['image/png', 'image/jpeg', 'application/pdf'],
})
```

Then call `uploads.mount(server)` in `server/main.ts` in place of `mountUploads(server)`. With `url` set, stored files link straight to the bucket's public domain, and the `GET` route is only a fallback. For a server-only app, you can pass the driver in `config/uploads.ts` instead and keep the provider. See [`UploadsDriver`](/packages/uploads/api) in the API reference.

## Next steps

- [API reference](/packages/uploads/api): every export of `kitr/uploads`, `kitr/uploads/react`, `kitr/uploads/server` and `kitr/uploads/provider`.
- [server](/packages/server): `createServer`, `bodyLimit` and the error shape.
- [api](/packages/api): controllers and routes for files that belong to a record.
- [forms](/packages/forms): show `fieldErrors` under the file input.
- [MDN on FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData): what `upload()` sends.


# Web API

Source: https://kitr.dev/packages/web/api

Every export of `kitr/web`, `kitr/web/client`, `kitr/web/provider`, `kitr/web/vite`, `kitr/web/kitr`, read from the published type definitions. The [guide](/packages/web) shows them in use.

## kitr/web

### pwaManifest

```ts
function pwaManifest(options: WebOptions, appName: string): {
  name: string;
  short_name: string;
  description: string | undefined;
  theme_color: string;
  background_color: string;
  display: "standalone" | "fullscreen" | "minimal-ui" | "browser";
  start_url: string;
  icons: {
    src: string;
    sizes: string;
    type?: string;
    purpose?: string;
  }[];
};
```

The manifest vite-plugin-pwa gets, from `web({ pwa })` and the app name.

### startWeb

```ts
function startWeb(ctx: PlatformContext, options: {
  mode: WebMode;
  port: number;
  host: string;
}): Promise<void>;
```

Serve a built web platform: the Start server bundle for `ssr`, static files otherwise.

### web

```ts
const web: import("@kitr/core").PlatformFactory<WebOptions>;
```

The web platform. List it in kitrrc.ts under `platforms`:

```ts
platforms: { site: web({ mode: 'ssr', pwa: true, port: 3000 }) }
```
`kitr dev site` starts Vite, `kitr build site` writes `dist/site`, `kitr start site` serves it.

### PwaOptions

```ts
interface PwaOptions {
  /** Full app name in the install dialog. Default: the app name from package.json. */
  name?: string;
  /** Name under the home-screen icon. Default: `name`, then the app name. */
  shortName?: string;
  /** Manifest description. */
  description?: string;
  /** Browser UI color. Default `#0f172a`. */
  themeColor?: string;
  /** Splash screen background. Default `#ffffff`. */
  backgroundColor?: string;
  /** How the installed app opens. Default `standalone`. */
  display?: 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
  /** Page the installed app opens on. Default `/`. */
  startUrl?: string;
  /** Manifest icons. Default `/icons/icon-192.png` and `/icons/icon-512.png` (maskable). */
  icons?: Array<{
    src: string;
    sizes: string;
    type?: string;
    purpose?: string;
  }>;
  /** `autoUpdate` reloads on a new version; `prompt` lets `useServiceWorker()` show a banner. Default `prompt`. */
  registerType?: 'autoUpdate' | 'prompt';
  /** Enable the service worker in `kitr dev`. Default false. */
  devEnabled?: boolean;
  /** Raw vite-plugin-pwa options merged last. */
  plugin?: Record<string, unknown>;
}
```

The manifest and service worker settings of an installable web platform, passed as `web({ pwa: { ... } })`.

### WebOptions

```ts
interface WebOptions {
  /**
   * `ssr`: TanStack Start renders on the server (needs a Node-ish host).
   * `static`: every route is prerendered at build time to plain HTML, served from any CDN.
   * `spa`: one shell, client rendering, served from any static host. Default `spa`.
   */
  mode: WebMode;
  /** Dev server and production port. Default 3000. */
  port: number;
  /** Interface to bind. Default: Vite's (localhost) in dev, `0.0.0.0` for `kitr start`. */
  host?: string;
  /** Installable app: manifest and service worker. `true` uses the app name; an object sets the manifest. */
  pwa: boolean | PwaOptions;
  /** Public base path, for apps served under a sub-path. Default `/`. */
  base: string;
  /** Open the browser on `kitr dev`. Default false. */
  open: boolean;
}
```

Options of the web platform, as written in `web({ ... })` in kitrrc.ts and edited by `kitr config <name>`.

### WebMode

```ts
type WebMode = 'static' | 'spa' | 'ssr';
```

How a web platform renders: prerendered HTML (`static`), a client-rendered shell (`spa`) or per-request server rendering (`ssr`).

## kitr/web/client

### useInstallPrompt

```ts
function useInstallPrompt(): {
  canInstall: boolean;
  installed: boolean;
  install: () => Promise<"unavailable" | "accepted" | "dismissed">;
};
```

Captures the browser's install prompt so the app can show its own button.
`canInstall` is false on browsers that do not fire the event (Safari) and after install.

### useServiceWorker

```ts
function useServiceWorker(options?: {
  path?: string;
  onNeedRefresh?: () => void;
}): {
  needRefresh: boolean;
  offlineReady: boolean;
  update: () => void;
  registration: ServiceWorkerRegistration | null;
};
```

Registers the service worker vite-plugin-pwa emits (`/sw.js`) and reports a waiting update.
With `registerType: 'prompt'`, call `update()` to activate it and reload.

## kitr/web/provider

### webProvider

```ts
const webProvider: import("@kitr/core").KitrProvider;
```

Runtime provider of the web platform. Registers the `platform` driver that tells
`kitr/platform` the app runs in a browser (or on the server rendering for one).

## kitr/web/vite

### kitrPwa

```ts
function kitrPwa(options: WebOptions, appName: string): Promise<Plugin[]>;
```

vite-plugin-pwa configured from `web({ pwa })`. The kitr() Vite plugin adds it when the
running web platform has `pwa` on; call it yourself only for a custom Vite setup.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->


# Web

Source: https://kitr.dev/packages/web

A marketing page that must load fast from a CDN, a dashboard behind a login, a store that needs every product page indexed: each one ships to the browser in a different way. `kitr/web` is the web platform. One line in `kitrrc.ts` says whether your `app/` builds to prerendered HTML, a single-page app or a server-rendered app, and whether people can install it to their home screen.

It is built on [Vite](https://vite.dev) and [TanStack Start](https://tanstack.com/start/latest), with [vite-plugin-pwa](https://vite-pwa-org.netlify.app) for installable apps. kitr adds the platform contract on top: `kitr dev`, `kitr build` and `kitr start` know how to run each mode, `kitr config` edits the options, and `kitr doctor` checks the setup.

The platform options run in the CLI and the Vite plugin; the hooks in `kitr/web/client` run in the browser. To ship the same app as a native iOS or Android app, add the [Mobile](/packages/mobile) platform next to this one. For a desktop window, use [Desktop](/packages/desktop). For an API with no UI, use the [Server](/packages/server) platform.

The examples on this page build the Acme orders app at `app.acme.com`: Ada's team lists orders and invoices in the browser, and later makes the app installable.

## Install

Add a web platform named `site`:

```sh
kitr add web site
```

`web` is the platform type and `site` is the name you address it by (`kitr dev site`). `kitr add web` with no name stops and prints `kitr add web <name> [--option value]   e.g. kitr add web site`, because `web` is a platform type, not a package.

What `kitr add web site` does:

- Installs `@kitr/web`, `@tanstack/react-start`, and `vite`, `@vitejs/plugin-react` and `@tanstack/router-plugin` as dev dependencies. With `--pwa` it adds `vite-plugin-pwa` (dev). With `--mode ssr` it adds `srvx`.
- Adds `@kitr/web` to `packages` in `kitrrc.ts`.
- Adds `() => import('@kitr/web/provider')` to `providers` in `kitrrc.ts`.
- Writes `site: web({...})` into `platforms` in `kitrrc.ts`, with the flags you passed as options, and adds `import { web } from 'kitr/web'`.
- Runs the [Router](/packages/router) recipe if it is missing, which runs the [React](/packages/react) recipe first. Together they write `app/app.ts`, `app/client.tsx`, `app/router.tsx` and the starter routes.
- Sets the `dev`, `build` and `start` scripts in `package.json` to `kitr dev`, `kitr build` and `kitr start`.
- With `--pwa`, writes `public/icons/README.md`, a note naming the two icons the manifest points at.
- Adds a `kitr: platform site` section to `AGENTS.md`. It tells agents how `kitr dev`, `kitr build` and `kitr start` behave for the chosen mode, and with `pwa` to render an update banner once.

`kitr/web` writes no `config/*.ts` file and adds no env variables.

Platform options are flags on the same command. A flag without a value means `true`:

```sh
kitr add web site --mode ssr --pwa --port 3000
```

| Flag | Default | Effect |
| --- | --- | --- |
| `--mode` | `spa` | `static`, `spa` or `ssr`. |
| `--port` | `3000` | Port for `kitr dev site` and `kitr start site`. |
| `--host` | | Interface to bind. |
| `--pwa` | `false` | Make the app installable. Installs `vite-plugin-pwa`. |
| `--base` | `/` | Public base path. |
| `--open` | `false` | Open the browser on `kitr dev`. |
| `--no-scaffold` | | Register the platform without writing files. |
| `--no-install` | | Edit `package.json` without running the package manager. |
| `--dry-run` | | Print what would change. |

An unknown flag stops the command: `web has no option "ssr" (options: mode, port, host, pwa, base, open)`.

Every kit except `server` already has a web platform named `site`. `blank`, `app` and `desktop` use `spa`; `fullstack`, `saas`, `site` and `realtime` use `ssr`; `mobile` uses `spa` with `pwa: true`. `kitr new` takes the same options for it:

```sh
kitr new acme-orders --kit app --mode ssr --pwa --port 3000
```

`kitr platforms remove site` takes the platform out of `kitrrc.ts`. It leaves `@kitr/web`, its provider and the files under `app/` in place, because other platforms may still use them.

## Configure

`kitr/web` has no config file. Its options live on the `web()` call in `kitrrc.ts`:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/web'],
  providers: [() => import('@kitr/web/provider')],
  platforms: {
    site: web({ mode: 'ssr', port: 3000, pwa: true }),
  },
})
```

| Option | Default | Description |
| --- | --- | --- |
| `mode` | `'spa'` | `static`: prerender every route to HTML at build time. `spa`: one HTML shell, client routing. `ssr`: render each request on the server through TanStack Start, then hydrate. |
| `port` | `3000` | Dev and production port. Must be a number between 0 and 65535. |
| `host` | | Interface to bind. Vite's default (`localhost`) in dev, `0.0.0.0` for `kitr start`. |
| `pwa` | `false` | `true` makes the app installable: a web manifest and a service worker. An object sets the manifest (see below). |
| `base` | `'/'` | Public base path, for apps served under a sub-path. |
| `open` | `false` | Open the browser on `kitr dev`. |

When `pwa` is an object, it takes these options:

| Option | Default | Description |
| --- | --- | --- |
| `pwa.name` | the app name | Full name in the install dialog. The app name comes from `package.json` (`acme-orders` becomes `Acme Orders`). |
| `pwa.shortName` | `pwa.name`, then the app name | Name under the home-screen icon. |
| `pwa.description` | | Manifest description. |
| `pwa.themeColor` | `'#0f172a'` | Browser UI color. |
| `pwa.backgroundColor` | `'#ffffff'` | Splash screen background. |
| `pwa.display` | `'standalone'` | `standalone`, `fullscreen`, `minimal-ui` or `browser`. |
| `pwa.startUrl` | `'/'` | Page the installed app opens. |
| `pwa.icons` | `/icons/icon-192.png` and `/icons/icon-512.png` | Manifest icons, `{ src, sizes, type?, purpose? }`. The 512 icon is `any maskable`. |
| `pwa.registerType` | `'prompt'` | `prompt` waits for you to call `update()` from `useServiceWorker()`. `autoUpdate` activates a new worker as soon as it installs. |
| `pwa.devEnabled` | `false` | Run the service worker under `kitr dev` too. |
| `pwa.plugin` | | Raw [vite-plugin-pwa options](https://vite-pwa-org.netlify.app/guide/), merged last. |

Write options as literals. The `kitr()` Vite plugin reads `kitrrc.ts` as text without running it, so `web({ mode: siteMode })` with a variable reaches the CLI but not the build.

An unknown mode fails when `kitrrc.ts` loads:

```
[kitr] Invalid options for web platform:
  mode: mode must be one of static, spa, ssr
```

A bad port fails the same way with `port: port must be a number between 0 and 65535`.

| Variable | Used for |
| --- | --- |
| `KITR_SITE_<OPTION>` | Overrides one option for one run of the CLI: `KITR_SITE_PORT=4000 kitr dev site`. The platform name is upper-cased, with other characters turned into `_`. |
| `PORT` | The port `kitr start` listens on when no `--port` flag is given. Wins over the `port` option. |
| `HOST` | The interface `kitr start` binds when no `--host` flag is given. |
| `KITR_PLATFORM` | Set by `kitr dev`, `kitr build` and `kitr start` to the platform name. The Vite plugin uses it to pick the platform it builds. |

The other platform types each have their own guide and options table: [Server](/packages/server), [Desktop](/packages/desktop) and [Mobile](/packages/mobile). [Platforms](/docs/platforms) lists them side by side.

## Ship your first page

Start from a project with a web platform (`kitr new acme-orders`, or `kitr add web site`). Replace the home route with the order list:

```tsx
// app/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

const orders = [
  { id: 'ord_1042', customer: 'Ada', total: 129 },
  { id: 'ord_1043', customer: 'Grace', total: 84 },
]

export const Route = createFileRoute('/')({
  component: OrdersPage,
})

function OrdersPage() {
  return (
    <main>
      <h1>Acme orders</h1>
      <ul>
        {orders.map((order) => (
          <li key={order.id}>
            {order.id}: {order.customer}, ${order.total}
          </li>
        ))}
      </ul>
    </main>
  )
}
```

Run it:

```sh
kitr dev site
```

Vite starts on `http://localhost:3000/` and you see the two orders. Edits to the file reload the page. `kitr dev` with no name starts every platform in `kitrrc.ts` at once.

When it looks right, build it and serve the build:

```sh
kitr build site
kitr start site
# ✔ site: serving dist/site on http://localhost:3000/
```

## Choose a rendering mode

All three modes are the same `app/` built through TanStack Start. Switching is a one-word change, so pick by where you host and what search engines need to see.

| `mode` | What you get | Host on | Use it for |
| --- | --- | --- | --- |
| `static` | Every route prerendered to an HTML file at build time. | Any static host or CDN. | Marketing pages, docs, a blog. |
| `spa` | One HTML shell; routes render in the browser. | Any static host. | Apps behind a login, where pages need no indexing. |
| `ssr` | Each request rendered on the server, then hydrated. | A Node-like host that runs `kitr start`. | Stores and apps whose pages must be indexed with live data. |

Change the mode in place:

```sh
kitr config site mode ssr
# ✔ site.mode = "ssr"
```

`kitr config` validates the value against the platform's options before it writes `kitrrc.ts`. Run `kitr add web site --mode ssr` again, or install `srvx` yourself, when you move to `ssr`: `kitr start` needs it to serve the server bundle.

Loaders run where the page renders. In `spa` mode they run in the browser. In `static` mode they run once at build time, so data must exist when you build or be fetched on the client. In `ssr` mode they run on the server for the first request and in the browser after that.

## Render on the server

In `ssr` mode every route renders on the server by default. To keep one route client-only, spread `ssrRoute(false)` from [SEO](/packages/seo) into it:

```tsx
// app/routes/orders.$orderId.edit.tsx
import { createFileRoute } from '@tanstack/react-router'
import { ssrRoute } from 'kitr/seo'

export const Route = createFileRoute('/orders/$orderId/edit')({
  ...ssrRoute(false),
  component: EditOrder,
})

function EditOrder() {
  const { orderId } = Route.useParams()
  return <h1>Edit {orderId}</h1>
}
```

`ssrRoute('data-only')` runs the loader on the server and renders the component in the browser. With the [Server](/packages/server) platform in the same project, an `ssr` web platform also answers `/api/*` through `app/routes/api.$.ts`, so one process serves pages and the API.

## Prerender pages

A `static` platform prerenders `/` and every page linked from it. To add pages that nothing links to, or to prerender a few pages of an `ssr` app, list them in `config/seo.ts` (written by `kitr add seo`):

```ts
// config/seo.ts
import { defineConfig } from 'kitr/seo'

export default defineConfig({
  site: { name: 'Acme', url: 'https://app.acme.com' },
  prerender: { routes: ['/pricing', '/changelog'], crawlLinks: true },
})
```

`kitr build site` writes one HTML file per page under `dist/site/client`. `site.url` also turns on `sitemap.xml`.

Keep `crawlLinks: true` in a `static` platform. The array form, `prerender: ['/pricing']`, turns link crawling off, so only `/` and the listed pages are written.

## Run more than one web platform

Names are yours, so one project can hold several web platforms. Each one gets its own port, its own mode and its own `dist/<name>` folder:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/web'],
  providers: [() => import('@kitr/web/provider')],
  platforms: {
    www: web({ mode: 'static', port: 3000 }),
    admin: web({ mode: 'spa', port: 3002 }),
  },
})
```

Add the second one from the command line:

```sh
kitr add web admin --mode spa --port 3002
kitr dev www admin
```

Both platforms build the same `app/`. To render something only in one of them, read the platform name at build time (see "Branch on the platform at build time").

## Change options from the command line

`kitr config` reads and writes platform options in `kitrrc.ts`:

```sh
kitr config site
# site (web)
#   mode         ssr            static (prerendered HTML), spa (client-rendered shell) or ssr (server-rendered) [static|spa|ssr]
#   port         3000           Dev and production port
#   host         unset          Host to bind (default: localhost in dev, 0.0.0.0 in production)
#   pwa          true           Installable app with a manifest and service worker
#   base         /              Public base path
#   open         false          Open the browser on dev
#
#   Override at runtime with KITR_SITE_<OPTION>=... or `kitr dev site --<option> value`.
kitr config site port 4000
kitr config site pwa --unset
```

To change an option for one run only, pass it as a flag or an env variable:

```sh
kitr dev site --port 4000 --open
KITR_SITE_PORT=4000 kitr dev site
```

Use run-time overrides for `port`, `host` and `open`. The Vite plugin reads `mode` and `pwa` from `kitrrc.ts` itself, so an override of those changes what the CLI does but not what Vite builds. Change them in the file.

## Open the dev server to your network

To try the app on a phone on the same Wi-Fi, bind every interface:

```sh
kitr dev site --host 0.0.0.0
```

Vite prints a `Network:` URL such as `http://192.168.1.20:3000/`. Open it on the phone. Set `host: '0.0.0.0'` in `kitrrc.ts` to make it the default.

The dev server uses Vite's `--strictPort`, so if port 3000 is taken, `kitr dev` fails instead of moving to 3001. Pick another port with `--port`.

## Serve the app under a sub-path

When the app lives at `acme.com/orders/` instead of its own domain, set `base`:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/web'],
  providers: [() => import('@kitr/web/provider')],
  platforms: {
    site: web({ mode: 'spa', base: '/orders/' }),
  },
})
```

This release records `base` but the `kitr()` Vite plugin does not pass it to Vite yet. Set Vite's own `base` to the same value:

```ts
// vite.config.ts
import { kitr } from 'kitr/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  base: '/orders/',
  plugins: [kitr()],
})
```

## Make the app installable

Turn on `pwa` and the build writes a web manifest and a service worker:

```sh
kitr config site pwa true
pnpm add -D vite-plugin-pwa
```

`kitr config` only edits `kitrrc.ts`, so install `vite-plugin-pwa` yourself when you turn `pwa` on after `kitr add` (`kitr add web site --pwa` installs it for you). `kitr doctor` reports it when it is missing.

The manifest uses the app name from `package.json`. To set it yourself, pass an object:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/web'],
  providers: [() => import('@kitr/web/provider')],
  platforms: {
    site: web({
      mode: 'spa',
      pwa: { name: 'Acme Orders', shortName: 'Orders', themeColor: '#0b5fff' },
    }),
  },
})
```

Put the two icons the manifest points at in `public/icons/`: `icon-192.png` (192x192) and `icon-512.png` (512x512, with the logo inside the maskable safe zone). `kitr add web site --pwa` leaves a `README.md` there as a reminder.

`pwaManifest()` shows the manifest a set of options produces, which helps when you check icons or colors:

```ts
// scripts/print-manifest.ts
import { pwaManifest, web } from 'kitr/web'

const site = web({ pwa: { name: 'Acme Orders', shortName: 'Orders', themeColor: '#0b5fff' } })
console.log(pwaManifest(site.options, 'Acme'))
// => {
//   name: 'Acme Orders',
//   short_name: 'Orders',
//   description: undefined,
//   theme_color: '#0b5fff',
//   background_color: '#ffffff',
//   display: 'standalone',
//   start_url: '/',
//   icons: [
//     { src: '/icons/icon-192.png', sizes: '192x192', type: 'image/png' },
//     { src: '/icons/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'any maskable' },
//   ],
// }
```

The service worker is emitted by `kitr build` only. It precaches the client build and serves the app shell for navigations, except under `/api/`, `/ws` and `/_serverFn/`, so API calls, sockets and server functions always reach the network.

## Show your own install button

Browsers that support installation fire `beforeinstallprompt` once. `useInstallPrompt()` from `kitr/web/client` keeps that event so you can show the dialog from your own button:

```tsx
// app/components/install-button.tsx
import { useInstallPrompt } from 'kitr/web/client'

export function InstallButton() {
  const { canInstall, installed, install } = useInstallPrompt()
  if (installed) return <p>Acme Orders is on your home screen.</p>
  if (!canInstall) return null
  return (
    <button type="button" onClick={() => install()}>
      Install Acme Orders
    </button>
  )
}
```

The hook returns three things:

| Field | Description |
| --- | --- |
| `canInstall` | `true` once the browser offered installation. `false` in Safari, which never fires the event, and after install. |
| `installed` | `true` after the browser fires `appinstalled`. |
| `install()` | Shows the browser dialog. Resolves to `'accepted'`, `'dismissed'`, or `'unavailable'` when there is nothing to show. |

```ts
const outcome = await install()
// => 'accepted'
```

After `'accepted'`, `canInstall` turns `false`. On iOS, people install from Safari's Share menu, so show a short hint there instead of the button.

## Offer an update when a new version ships

With the default `registerType: 'prompt'`, a new service worker waits until you tell it to take over. Render one banner near the root of the app:

```tsx
// app/components/pwa-update.tsx
import { useServiceWorker } from 'kitr/web/client'

export function PwaUpdate() {
  const { needRefresh, update } = useServiceWorker()
  if (!needRefresh) return null
  return (
    <div role="status">
      A new version of Acme Orders is ready.{' '}
      <button type="button" onClick={() => update()}>
        Reload
      </button>
    </div>
  )
}
```

```tsx
// app/routes/__root.tsx
import type { KitrRouterContext } from 'kitr/router'
import { createRootRouteWithContext, HeadContent, Outlet, Scripts } from 'kitr/router'
import { PwaUpdate } from '#app/components/pwa-update'

export const Route = createRootRouteWithContext<KitrRouterContext>()({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1, viewport-fit=cover' },
    ],
    links: [{ rel: 'manifest', href: '/manifest.webmanifest' }],
  }),
  component: RootLayout,
})

function RootLayout() {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <PwaUpdate />
        <Scripts />
      </body>
    </html>
  )
}
```

`useServiceWorker()` registers `/sw.js` and returns:

| Field | Description |
| --- | --- |
| `needRefresh` | `true` when a new worker is installed and waiting. |
| `offlineReady` | `true` when the first worker is active and the app works offline. |
| `update()` | Tells the waiting worker to activate, then reloads the page once it takes control. |
| `registration` | The `ServiceWorkerRegistration`, or `null` before registration finishes. |

kitr registers the worker itself, so vite-plugin-pwa injects no script and no tags of its own. TanStack Start renders the HTML from the root route, so the `manifest` link goes in its `head()`, as above. Render `PwaUpdate` once: two copies register twice.

To run code when an update arrives, pass `onNeedRefresh`. Wrap it in `useCallback`, because a new function on every render registers the worker again:

```tsx
// app/components/pwa-update-toast.tsx
import { useCallback } from 'react'
import { useServiceWorker } from 'kitr/web/client'

export function PwaUpdateToast({ notify }: { notify: (message: string) => void }) {
  const onNeedRefresh = useCallback(() => notify('Acme Orders has an update.'), [notify])
  useServiceWorker({ onNeedRefresh })
  return null
}
```

To skip the banner, set `registerType: 'autoUpdate'` in the `pwa` object. The new worker then activates as soon as it installs, without waiting for `update()`.

## Test the service worker in development

The worker is off under `kitr dev` so stale caches never hide your edits. To debug install and offline behaviour, turn it on:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/web'],
  providers: [() => import('@kitr/web/provider')],
  platforms: {
    site: web({ mode: 'spa', pwa: { devEnabled: true } }),
  },
})
```

For a run closer to production, use `kitr build site && kitr start site` and test against that. Turn `devEnabled` off again when you are done.

## Pass options to vite-plugin-pwa

Anything kitr does not expose goes in `pwa.plugin`. It is merged last into the [vite-plugin-pwa options](https://vite-pwa-org.netlify.app/guide/), so it wins over kitr's defaults:

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'

export default defineKitrConfig({
  packages: ['@kitr/react', '@kitr/router', '@kitr/web'],
  providers: [() => import('@kitr/web/provider')],
  platforms: {
    site: web({
      mode: 'spa',
      pwa: {
        name: 'Acme Orders',
        plugin: { includeAssets: ['favicon.svg'], workbox: { maximumFileSizeToCacheInBytes: 5000000 } },
      },
    }),
  },
})
```

`plugin.workbox` replaces kitr's whole `workbox` block, including the `/api/` denylist. Copy `navigateFallbackDenylist: [/^\/api\//, /^\/ws/, /^\/_serverFn\//]` into it when you override it.

## Use the PWA plugin in a custom Vite setup

The `kitr()` Vite plugin adds the PWA plugin when the platform it builds has `pwa` on. If you build without `kitr()`, add it yourself with `kitrPwa()` from `kitr/web/vite`:

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { web } from 'kitr/web'
import { kitrPwa } from 'kitr/web/vite'

const site = web({ pwa: { name: 'Acme Orders' } })

export default defineConfig(async () => ({
  plugins: [await kitrPwa(site.options, 'Acme Orders')],
}))
```

`kitrPwa()` resolves to the vite-plugin-pwa plugins with the manifest from `pwaManifest()`, the `/api/` denylist and the update behaviour from `registerType`. It skips the server build of TanStack Start, so the worker is generated for the client only.

## Branch on the platform at build time

The `kitr()` Vite plugin defines two constants for the platform it builds. Use them to drop code from one platform's bundle:

```tsx
// app/components/footer.tsx
export function Footer() {
  if (import.meta.env.KITR_PLATFORM === 'admin') return <footer>Acme admin</footer>
  return <footer>Acme · app.acme.com</footer>
}
```

| Constant | Value |
| --- | --- |
| `import.meta.env.KITR_PLATFORM` | The platform name from `kitrrc.ts`, such as `'site'` or `'admin'`. |
| `import.meta.env.KITR_PLATFORM_TYPE` | The platform type: `'web'`, `'mobile'` or `'desktop'`. |

Without `KITR_PLATFORM` (a plain `vite` run), the plugin builds the first web platform in `kitrrc.ts`.

## Detect the browser at run time

`kitr/web/provider` registers the `platform` driver for the browser: type `web`, not native, the OS read from the user agent, and `standalone` when the app runs installed. Read it through [Platform](/packages/platform):

```tsx
// app/components/install-hint.tsx
import { usePlatform } from 'kitr/platform/react'

export function InstallHint() {
  const platform = usePlatform()
  if (platform.standalone) return null
  if (platform.is('ios')) return <p>Tap Share, then Add to Home Screen.</p>
  return null
}
```

During server rendering the driver reports the OS as `'server'`. The web driver has the lowest priority, so inside a native shell the [Mobile](/packages/mobile) or [Desktop](/packages/desktop) driver wins.

## Build for production

`kitr build site` runs `vite build` with `KITR_PLATFORM=site` and writes everything under `dist/site`:

| Path | Mode | Contents |
| --- | --- | --- |
| `dist/site/client/` | all | JavaScript, CSS and assets. |
| `dist/site/client/index.html` | `spa` | The app shell. |
| `dist/site/client/**/index.html` | `static` | One HTML file per prerendered page. |
| `dist/site/server/server.js` | `ssr` | The TanStack Start server bundle. |
| `dist/site/client/sw.js`, `manifest.webmanifest` | `pwa` | The service worker and the manifest. |

`kitr build` with no name builds every platform, one after another.

## Serve the build

`kitr start site` serves the build with [srvx](https://srvx.h3.dev) on the platform's port, bound to `0.0.0.0`:

```sh
kitr start site --port 8080
# ✔ site: serving dist/site on http://localhost:8080/
```

- In `static` and `spa` mode it serves `dist/site/client` and answers unknown paths with the shell (`index.html`, `_shell.html` or `200.html`), so client routes survive a reload.
- In `ssr` mode it serves static files first and hands every other request to the `fetch` export of `dist/site/server/server.js`. When `crossws` is installed, WebSocket upgrades work too.
- Every file under `dist/site/client` is sent with `Cache-Control: max-age=31536000` (one year). That suits hashed assets, but this release applies it to HTML files and `sw.js` too, so a browser may keep an old page after you deploy. Put a proxy or CDN rule in front that sends `no-cache` for `*.html` and `/sw.js`.
- `SIGINT` and `SIGTERM` close the server cleanly.

On a host that sets `PORT` (Render, Fly.io, Railway), run `kitr start site` and the env variable picks the port.

## Deploy a static site or SPA to a CDN

A `static` or `spa` build needs no server. Upload `dist/site/client` to any static host:

```sh
kitr build site
npx wrangler pages deploy dist/site/client --project-name acme-orders
```

For `spa`, tell the host to answer unknown paths with `index.html` (on Netlify, a `_redirects` line `/* /index.html 200`). Without it, reloading `/orders/ord_1042` returns a 404.

## Commands

`kitr/web` adds no generators. The web platform answers these commands:

| Command | What it does |
| --- | --- |
| `kitr add web <name>` | Adds a web platform: installs the packages, writes `platforms.<name>` in `kitrrc.ts`, runs the router recipe and adds the scripts. |
| `kitr dev [names...]` | Runs `vite dev --port <port> --strictPort`, plus `--host` and `--open` when set. |
| `kitr build [names...]` | Runs `vite build` into `dist/<name>`. |
| `kitr start [names...]` | Serves `dist/<name>` with srvx: static files, the SPA fallback, or the `ssr` server bundle. |
| `kitr config <name> [option] [value]` | Reads or sets an option in `kitrrc.ts`, validated first. `--unset` removes one. |
| `kitr platforms` | Lists every platform with its options. |
| `kitr platforms types` | Lists the platform types (`web`, `desktop`, `mobile`, `server`). |
| `kitr platforms scaffold <name>` | Writes the platform's files that are missing (`public/icons/README.md` with `pwa`). Existing files are kept. |
| `kitr platforms remove <name>` | Takes the platform out of `kitrrc.ts`. |

`kitr doctor` checks each web platform and reports:

- an error when `vite` is not installed. Fix: `pnpm add -D vite`.
- an error when `@tanstack/react-start` is not installed.
- an error when `pwa` is on but `vite-plugin-pwa` is not installed.
- a warning when `app/routes/__root.tsx` is missing. Fix: `kitr add router`.
- a warning when React is installed but `kitrrc.ts` lists no UI platform. Fix: `kitr add web site`.

## Errors

| Message | When | What to do |
| --- | --- | --- |
| `[kitr] Invalid options for web platform: mode: mode must be one of static, spa, ssr` | `kitrrc.ts` sets an unknown mode. | Use `static`, `spa` or `ssr`. |
| `[kitr] Invalid options for web platform: port: port must be a number between 0 and 65535` | The port is out of range or a string. | Pass a number. |
| `web has no option "<flag>" (options: mode, port, host, pwa, base, open)` | `kitr add web` got an unknown flag. | Use one of the listed options. |
| `Platform name "<name>" must be a short identifier (site, api, app, phone...)` | The name has spaces or starts with a digit. | Use letters, digits, `-` and `_`. |
| `No platform named "<name>" in kitrrc.ts (have: site, api)` | `kitr dev`, `build`, `start` or `config` got an unknown name. | Use a name from `kitr platforms`. |
| `dist/site/client not found. Run `kitr build site` first.` | `kitr start` ran before a build. | Run `kitr build site`. |
| `dist/site/server/server.js not found. Run `kitr build site` first.` | `ssr` mode, but the last build was `spa` or `static`. | Build again after changing the mode. |
| `dist/site/server/server.js does not export a fetch handler` | The server bundle is not a TanStack Start build. | Rebuild with the `kitr()` Vite plugin. |
| `[kitr/vite] KITR_PLATFORM=<name> is not a platform in kitrrc.ts (have: ...)` | Vite ran with a platform name that `kitrrc.ts` does not have. | Run through `kitr dev <name>`, or fix the variable. |
| `[kitr/vite] site: pwa is on but vite-plugin-pwa could not load (...)` | A warning: the build continues without a service worker. | `pnpm add -D vite-plugin-pwa`. |
| `Port 3000 is already in use` | Another process has the port, and `--strictPort` refuses to move. | Stop it or pass `--port`. |

## Testing

Platform options are plain values, so a test can load `kitrrc.ts` and check them. Run it in CI to catch a mode or port change nobody meant to make:

```ts
// test/platforms.test.ts
import { pwaManifest } from 'kitr/web'
import { describe, expect, it } from 'vitest'
import rc from '../kitrrc'

describe('the site platform', () => {
  it('is server-rendered and installable', () => {
    const site = rc.platforms!.site!
    expect(site.type).toBe('web')
    expect(site.options).toMatchObject({ mode: 'ssr', port: 3000 })
    expect(pwaManifest(site.options, 'Acme Orders')).toMatchObject({
      name: 'Acme Orders',
      display: 'standalone',
    })
  })
})
```

The hooks in `kitr/web/client` read browser events, so a test fires those events itself. This test renders the install button from "Show your own install button" with a fake `beforeinstallprompt` event, in Vitest's `happy-dom` environment:

```tsx
// test/install-button.test.tsx
import { act, fireEvent, render, screen } from '@testing-library/react'
import { describe, expect, it, vi } from 'vitest'
import { InstallButton } from '#app/components/install-button'

function installEvent(outcome: 'accepted' | 'dismissed') {
  return Object.assign(new Event('beforeinstallprompt', { cancelable: true }), {
    prompt: vi.fn(async () => {}),
    userChoice: Promise.resolve({ outcome }),
  })
}

describe('InstallButton', () => {
  it('stays hidden until the browser offers installation', () => {
    const { container } = render(<InstallButton />)
    expect(container.innerHTML).toBe('')
  })

  it('shows the browser dialog and confirms the install', async () => {
    render(<InstallButton />)
    const event = installEvent('accepted')
    act(() => void window.dispatchEvent(event))

    await act(async () => {
      fireEvent.click(screen.getByRole('button', { name: 'Install Acme Orders' }))
    })
    expect(event.prompt).toHaveBeenCalled()

    act(() => void window.dispatchEvent(new Event('appinstalled')))
    expect(screen.getByText('Acme Orders is on your home screen.')).toBeTruthy()
  })
})
```

`useServiceWorker()` does nothing when `navigator.serviceWorker` is missing, which is the case in `happy-dom`, so components that use it render without a stub. Test the real worker against `kitr build site && kitr start site` in a browser, for example with Playwright.

## Next steps

- [API reference](/packages/web/api)
- [Platform](/packages/platform): where the app runs, online state and safe areas, the same way on every platform
- [SEO](/packages/seo): head tags, prerender lists, the sitemap and `robots.txt`
- [Mobile](/packages/mobile): the same app on iOS and Android
- [Platforms](/docs/platforms): every platform type and the commands they share
- [TanStack Start documentation](https://tanstack.com/start/latest)


# Getting started

Source: https://kitr.dev/docs/getting-started

kitr is a React framework made of small packages you add as you need them. You start with a router and data loading, then run `kitr add forms` or `kitr add auth` when your app needs forms or sign-in. Each package is a popular library you may already know (TanStack Query, React Hook Form, Zustand...) with the setup done for you.

You need [Node.js](https://nodejs.org) 22 or newer.

## 1. Install the CLI once

```sh
npm install -g kitr
```

Now `kitr` works in any folder. Inside a project, the global command hands off to the project's own version of kitr, so everyone on the team runs the same one.

Prefer not to install globally? Every command on this site has a picker to switch to `pnpm`, `npx`, `yarn` or `bunx`, and remembers your choice.

## 2. Create an app

```sh
kitr new my-app --kit app
```

A **kit** is a starting set of packages. Pick the one closest to what you're building; you can add or remove packages later.

| Kit | For | Includes |
| --- | --- | --- |
| `blank` | Learning, or starting from nothing | Router and query |
| `app` | A logged-in app that talks to an existing API | Plus HTTP, forms, tables, state, UI, auth, mocks and testing |
| `fullstack` | An app with its own backend | The app kit plus server rendering, server actions, API routes and realtime channels |
| `server` | An API with no React at all | Server, API routes, database, realtime channels, logger and testing |

`kitr new` installs dependencies, sets up git and writes an `AGENTS.md` for coding assistants.

## 3. Run it

```sh
cd my-app
npm run dev
```

Open the URL it prints. Edit `app/routes/index.tsx` and the page updates as you save.

## 4. Add a page

Every file in `app/routes` is a page. Create `app/routes/projects.tsx`:

```tsx
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/projects')({
  component: () => <h1>Projects</h1>,
})
```

It's live at `/projects`. Or let the CLI write it: `kitr make:route projects`.

## 5. Add a package

Say you want users to save a list of favourites that survives a reload:

```sh
kitr add state
```

That one command installs the package, wires it up and notes the conventions in `AGENTS.md`. Every package page on this site starts with a live example, then shows exactly what `kitr add` changed.

## What next

- [Project structure](/docs/project-structure): where everything lives.
- [Configuration](/docs/configuration): `kitrrc.ts`, `config/` and environment variables.
- [Browse packages](/packages): find the pieces your app needs.
- [Loading and saving data](/docs/data): the one idea that ties kitr together.


# Project structure

Source: https://kitr.dev/docs/project-structure

A new app from the `app` kit looks like this. Folders appear as you add packages, so a `blank` app has fewer.

```
my-app/
├── app/
│   ├── routes/            # one file per page
│   │   ├── __root.tsx     # the layout around every page
│   │   └── index.tsx      # the home page, at /
│   ├── features/          # code grouped by feature: queries, forms, components
│   ├── components/ui/     # components copied in by `kitr ui add`; yours to edit
│   ├── stores/            # app-wide state (kitr add state)
│   ├── app.ts             # creates the app from kitrrc.ts and config/
│   ├── env.ts             # environment variables, validated at startup
│   ├── router.tsx         # creates the router
│   └── routeTree.gen.ts   # generated from app/routes; never edit
├── config/                # one file per package that has options
├── kitrrc.ts              # which packages are installed and wired
├── AGENTS.md              # conventions for coding assistants, kept up to date by kitr add
└── vite.config.ts         # one line: plugins: [kitr()]
```

## The three files that wire everything

**`kitrrc.ts`** lists the kitr packages in the project and their providers. Nothing is discovered by magic: if a package affects your app at startup, it's in this list.

**`config/<package>.ts`** holds one package's options, typed by that package's `defineConfig`. `config/query.ts` configures [Query](/packages/query), `config/http.ts` configures [HTTP](/packages/http), and so on.

**`app/env.ts`** declares your environment variables. Public ones (prefixed `VITE_`) reach the browser; server ones throw if browser code reads them. A missing or malformed variable stops the app at startup with a clear message, not halfway through a request.

## Features, not file types

Group code by what it does for the user rather than what kind of file it is:

```
app/features/projects/
├── queries.ts        # defineQuery / defineMutation for projects
├── project-form.tsx
└── project-list.tsx
```

The generators follow this: `kitr make:queries projects` writes `app/features/projects/queries.ts`.

## Full-stack and backend apps

A `fullstack` app adds server code beside the client:

```
app/
├── api/routes.ts       # API routes (kitr add api)
├── controllers/        # one class per resource
├── actions/            # server actions (kitr add actions)
└── channels/           # realtime channels (kitr add realtime)
```

A `server` app has no `app/routes` or React at all. See [A backend without React](/docs/pure-backend).


# Configuration

Source: https://kitr.dev/docs/configuration

kitr follows one rule for setup: **everything is written down where you can read it.** There's no hidden plugin discovery and no config buried in node_modules.

## kitrrc.ts

```ts
import { defineKitrConfig } from 'kitr/app'

export default defineKitrConfig({
  packages: ['@kitr/router', '@kitr/query', '@kitr/http', '@kitr/auth'],
  providers: [
    () => import('@kitr/query/provider'),
    () => import('@kitr/http/provider'),
    () => import('@kitr/auth/provider'),
  ],
  directories: { app: 'app', routes: 'app/routes', config: 'config' },
})
```

- `packages` is what `kitr doctor` checks against `package.json`.
- `providers` run in order at startup. Each is a lazy import, so a provider only loads when the app boots.
- `directories` tells the CLI and the Vite plugin where things live, if you move them.

`kitr add` and `kitr remove` edit this file for you, but it's yours: reorder it, add your own providers, delete what you don't use.

## config/

Each package with options reads them from `config/<name>.ts`:

```ts
// config/query.ts
import { defineConfig } from 'kitr/query'

export default defineConfig({ staleTime: 60_000 })
```

`defineConfig` gives you autocomplete and type checks for that package's options. Every option is documented on the package's page, under Configuration.

## Providers

A provider is how a package (or your own code) plugs into startup. It has up to five steps, each optional:

| Step | When | Typical use |
| --- | --- | --- |
| `register` | First, for every provider | Put a service in the container: `app.container.singleton('http', ...)` |
| `boot` | Before the first render or request | Restore the session, warm a cache |
| `wrap` | Client apps, while rendering | Put a React context provider around the app |
| `ready` | Server apps, once listening | Start a background job |
| `shutdown` | Server apps, on stop | Close database pools, flush logs |

Write your own with `kitr make:provider analytics`:

```ts
import { defineProvider } from 'kitr/app'

export default defineProvider({
  name: 'analytics',
  register(app) {
    app.container.singleton('analytics', () => createAnalytics(app.config.get('analytics')))
  },
})
```

Then add `() => import('#app/providers/analytics')` to `providers` in `kitrrc.ts`. Anywhere in the app, `useService('analytics')` (from `kitr/react`) or `app.container.use('analytics')` returns it.

## Environment variables

```ts
// app/env.ts
import { createEnv, env as e } from 'kitr/env'

export const env = createEnv({
  public: {
    VITE_API_URL: e.url({ default: 'http://localhost:3333' }),
  },
  server: {
    DATABASE_URL: e.url(),
    STRIPE_KEY: e.string(),
  },
})
```

Values come from `.env` files and the process environment. The app refuses to start if a required variable is missing or invalid, and reading a server variable from browser code throws instead of silently shipping your secret.

## Checking your setup

```sh
kitr doctor
```

Compares `kitrrc.ts` with `package.json`, checks every provider resolves, finds missing config files and flags direct imports of upstream libraries where a `kitr/*` entry exists. It exits with code 1 on errors, so you can run it in CI.


# Loading and saving data

Source: https://kitr.dev/docs/data

Apps get data from many places: a REST API someone else built, your own API routes, server functions, a WebSocket. Usually each comes with its own way of loading, caching and reporting errors, and your components end up knowing which is which.

In kitr, every source produces the same three things:

| Kind | What it does | Example |
| --- | --- | --- |
| **Query** | Reads data | The list of projects |
| **Mutation** | Changes data, then says what in the cache is now out of date | Rename a project |
| **Subscription** | A stream of events that update the cache | A teammate renamed a project |

Components only ever use queries, mutations and subscriptions. Swap a REST endpoint for a server action and no component changes.

## Where contracts come from

```ts
// An existing REST API (kitr add http)
defineQuery(httpQuery(http, { path: 'projects', key: () => projectKeys.list() }))

// Your own API routes (kitr add api)
defineQuery(api.projects.index.query())

// A server action (kitr add actions)
defineQuery(listProjects.query())

// Hand-written, for anything else
defineQuery({ key: () => projectKeys.list(), fetch: () => getProjectsSomehow() })
```

All four give you the same object, used the same way:

```tsx
const { data } = useSuspenseQuery(projectsQuery.options())
```

## Effects instead of manual refetching

The most common bug in data-heavy apps is a screen that shows stale data after a save. kitr fixes it at the source: a mutation declares what it changes.

```ts
export const renameProject = defineMutation(
  api.projects.update.mutation({
    effects: (project) => ({
      set: [{ key: projectKeys.detail(project.id), data: project }], // update this entry now
      invalidate: [projectKeys.lists()],                              // refetch every list
    }),
  }),
)
```

Every screen showing that project or a list of projects updates, without any component knowing the others exist. A realtime channel event can carry the same effects, so a change made in another browser lands in the same cache.

## Keys

A **key** names a piece of data in the cache. `createKeys` makes them consistent so effects can find what to update:

```ts
const projectKeys = createKeys('projects')

projectKeys.all            // ['projects']                       everything about projects
projectKeys.lists()        // ['projects', 'list']               every list
projectKeys.list({ page }) // ['projects', 'list', { page: 2 }]  one list
projectKeys.detail(id)     // ['projects', 'detail', '42']       one project
```

Invalidating a key also invalidates every key that starts with it.

## Errors

Whatever the source, a failure arrives as a `KitrError` with `code`, `status`, `message` and, for validation failures, `fieldErrors`. [Forms](/packages/forms) puts `fieldErrors` under the right inputs automatically.

## Learn more

- [Query](/packages/query): the full API
- [HTTP](/packages/http), [API routes](/packages/api), [server actions](/packages/actions), [realtime channels](/packages/realtime): the sources


# A dashboard on an existing API

Source: https://kitr.dev/docs/dashboard

This guide builds a small admin dashboard for a backend that already exists: users sign in, see a sortable table of projects, and create new ones. It uses the `app` kit, which has everything needed.

## 1. Create the app

```sh
kitr new projects-admin --kit app
```

Point it at your API in `.env`:

```
VITE_API_URL=https://api.example.com
```

No backend yet? The kit includes [Mocks](/packages/mocks), which fakes API responses while you build.

## 2. Sign in

`config/auth.ts` already uses a token adapter that posts to `/sign-in` and reads `/me`. Adjust the paths to match your API, then protect every page under a layout route:

```ts
// app/routes/_app.tsx
import { createFileRoute, Outlet } from '@tanstack/react-router'
import { requireAuth } from 'kitr/router'

export const Route = createFileRoute('/_app')({
  beforeLoad: requireAuth(),
  component: () => <Outlet />,
})
```

Wire the token into the HTTP client so every request is signed. See [Auth with the HTTP client](/packages/auth#with-the-http-client).

## 3. Describe the data

```sh
kitr make:queries projects
```

This writes `app/features/projects/queries.ts` with list, detail, create, update and delete, each backed by the HTTP client and wired with cache effects. Adjust the paths and the `Project` type to match your API.

## 4. Show a table

```sh
kitr ui add data-table
```

Then follow [Tables](/packages/table#sorting-and-paging-in-the-url) to bind sorting and paging to the URL. Pass the URL's `page`, `size` and `sort` to your list query so the API returns the right page.

## 5. Create projects

```sh
kitr make:form new-project
```

Point the form's `onSubmit` at the create mutation. When it succeeds, the effect invalidates the project lists and the table refetches. If your API responds `422` with field errors, they appear under the right inputs. See [Forms](/packages/forms).

## 6. Test it

The kit includes [Testing](/packages/testing). `renderWithKitr` renders a component with the app's providers, and the mocks answer its requests:

```sh
npm test
```

## Where to go next

- [Permissions](/packages/auth#permissions): hide the delete button from members.
- [State](/packages/state): remember the user's preferred table density.


# A full-stack app

Source: https://kitr.dev/docs/fullstack

When you own the backend too, keep it in the same project. The `fullstack` kit runs on [TanStack Start](https://tanstack.com/start): pages render on the server, server actions run on the server, and the browser calls both with full types.

```sh
kitr new tasks --kit fullstack
```

## Server actions or API routes?

Both run on your server. Pick by who calls them:

| Use | When |
| --- | --- |
| [Server actions](/packages/actions) | Only your own React app calls it. The quickest way: no routes, no client to set up. |
| [API routes](/packages/api) | Something else calls it too: a mobile app, a partner, a webhook. You get URLs, OpenAPI and a typed client. |

Many apps use actions for the UI and a handful of API routes for integrations.

## A server action

```sh
kitr make:mutation tasks/rename
```

```ts
// app/actions/tasks/rename.ts
import { defineMutation } from 'kitr/actions'
import { z } from 'zod'

export const renameTask = defineMutation('tasks.rename', {
  input: z.object({ id: z.string(), title: z.string().min(1) }),
  effects: (task) => ({ invalidate: [['tasks', 'list']] }),
  handler: async ({ input }) => db.tasks.update(input.id, { title: input.title }),
})
```

`kitr types` registers the name (it runs with `kitr dev`), so a component uses it with full types. Validation failures reach the form's fields; the effect refreshes every task list:

```tsx
const rename = useMutation('tasks.rename')
```

Reads are `defineQuery('tasks.list', { handler })`, used as `useSuspenseQuery('tasks.list')` in a component and `queryOptions('tasks.list')` in a loader.

## Live updates

With [Realtime](/packages/realtime), one channel definition serves both ends. The server publishes; every open browser applies the event's cache effects:

```ts
// app/channels/tasks.ts
export const tasksChannel = defineChannel<{ board: string }>({
  name: 'tasks',
  events: { changed: { effects: ({ board }) => ({ invalidate: [['tasks', 'list', { board }]] }) } },
  authorize: (session) => !!session,
})
```

## Server rendering and SEO

[SEO](/packages/seo) controls which pages render on the server and what goes in their `<head>`:

```ts
export const Route = createFileRoute('/tasks/$id')({
  head: ({ loaderData }) => seo({ title: loaderData.title, description: loaderData.summary }),
})
```

## Deploying

```sh
npm run build
npm start
```

`npm start` runs `kitr start`, which serves each platform's build (the site on srvx, the API on its runtime). The output is also a standard fetch handler, so platforms that run those directly work too.


# A backend without React

Source: https://kitr.dev/docs/pure-backend

`kitr new my-api --kit server` creates a backend whose dependency graph contains no React, no TanStack and no Vite:

```
my-api/
  kitrrc.ts              # platforms: { api: server({ runtime: 'node' }) }, providers: logger, db, realtime
  server/main.ts         # createServer({ providers, config }) + routes + realtime + listen()
  server/routes.ts       # defineRoutes(...)
  server/controllers/    # plain classes, one per resource
  server/realtime.ts     # createRealtimeServer({ channels })
  config/                # one file per package; config/index.ts is generated by `kitr add`
  app/channels/          # defineChannel(...)
  app/env.ts             # createEnv({ server: { PORT, LOG_LEVEL, DATABASE_URL } })
  test/                  # createTestClient(server).get('/api/health')
```

Run it with `kitr dev` (tsx watch, or `bun --watch`, `deno run --watch`, `wrangler dev` depending on `runtime`) or `kitr build && kitr start`. `kitr config api runtime bun` switches runtime; `kitr config api port 8080` or `KITR_API_PORT=8080` changes the port. `kitr api:sync` writes `openapi.json` and a route table; `kitr routes:list` prints the routes.

## What you get

- **Router**: `defineRoutes` with groups, prefixes, named routes, `resource('projects', Controller)` for the five REST actions, per-route and per-group middleware (`cors()`, `rateLimit()`, `requireJson()`, your own `defineMiddleware`).
- **Controllers**: classes whose methods take an `HttpContext` (`params`, `query`, `body`, `request`, `response`, `locals`, `logger`, `requestId`, `app`). `static validation = { store: { body: schema } }` validates before the method runs and types the client.
- **Errors**: throw `KitrError.notFound('Project')`, `KitrError.validation(fieldErrors)` or anything else; every response has the same `{ code, message, status, fieldErrors? }` shape the client already understands.
- **Lifecycle**: providers run `register → boot → ready → shutdown`; `server.listen()` wires SIGINT/SIGTERM to `shutdown` with a timeout. The request-scoped container (`useRequestApp()`) forks the app per request.
- **Realtime**: `createRealtimeServer({ channels, authorize })` over WebSocket (crossws), Socket.IO or SSE, chosen in `config/realtime.ts`; `realtime.use(channel, params).emit(event, data)` from a controller. The client side (`kitr/realtime`) can live in any frontend, kitr or not.
- **Auth**: `kitr/auth/server` gives `authMiddleware({ verify })`, `requireUser()`, `currentUser()` and `can()` on the API side with the same `defineAbilities` the client uses.
- **Database**: `defineDb({ connect, disconnect })` in `config/db.ts` with the ORM of your choice; no ORM is bundled.
- **Typed client for the frontend**: `export type AppRoutes = typeof routes.$types` in the backend, `createApiClient<AppRoutes>()` in the frontend. Share the type through a workspace package or a `.d.ts`; there is no generated code to keep in sync.

## Mixing

A kitr React app that later needs its own backend keeps the same packages: `kitr add server api` adds the `api` platform, `server/main.ts` and `app/routes/api.$.ts`, which mounts the same router inside TanStack Start, so `kitr dev` runs both and `kitr dev site` runs just the UI. A standalone backend plus a `--kit app` frontend is the other valid shape; `kitr doctor` keeps React out of the backend either way.


# Working with coding agents

Source: https://kitr.dev/docs/agents

kitr is designed so that a coding assistant (Claude Code, Cursor, Copilot, Codex) makes the same choices you would.

## Everything runs from flags

No kitr command prompts. `kitr new my-app --kit app --pm pnpm`, `kitr add auth`, `kitr make:form invite` and `kitr doctor` all run start to finish from their arguments, so an agent or a CI job never gets stuck waiting for input.

## AGENTS.md is kept up to date

`kitr new` writes an `AGENTS.md` at the project root, and every `kitr add` appends that package's conventions, such as "import from `kitr/query`, never from `@tanstack/react-query`" or "mutations declare effects; never invalidate inline". `kitr remove` takes them out again. Most agents read `AGENTS.md` automatically.

## Explicit wiring

Because every provider is listed in `kitrrc.ts` and every option lives in `config/`, an agent can see the whole setup in two places instead of guessing what a plugin did.

## Checks it can run

```sh
kitr doctor --json
```

Machine-readable findings with suggested fixes, and exit code 1 on errors. Ask your agent to run it after any change to dependencies or wiring.

## Docs for models

This site publishes [llms.txt](/llms.txt), an index of every page, and [llms-full.txt](/llms-full.txt), every page in one file. Every page is also available as markdown by adding `.md` to its URL.


# Building a package

Source: https://kitr.dev/docs/building-packages

Every package on this site, official or not, is an ordinary npm package with three additions: a `kitr` block in its `package.json`, a `docs` folder, and optionally an `examples` folder. Nothing is registered by hand. Publish it with the `kitr-package` keyword and it can be listed here.

## The manifest

```json
{
  "name": "kitr-stripe",
  "version": "1.0.0",
  "keywords": ["kitr", "kitr-package"],
  "files": ["dist", "docs"],
  "kitr": {
    "name": "stripe",
    "title": "Stripe",
    "summary": "Take card payments and subscriptions, with checkout pages you can restyle.",
    "category": "backend",
    "runsOn": "both",
    "builtOn": ["stripe"],
    "requires": ["server"],
    "docs": "docs"
  }
}
```

| Field | Required | Description |
| --- | --- | --- |
| `name` | yes | The short name people type: `kitr add stripe`. |
| `title` | yes | Display name on this site. |
| `summary` | yes | One sentence, 140 characters at most, on what it does for the app. See below. |
| `category` | yes | One of `data-fetching`, `app-state`, `backend`, `realtime`, `interface`, `forms`, `auth`, `pages`, `platforms`, `device`, `insights`, `dev-tools`. Sets the colour and filter on the packages page. |
| `runsOn` | yes | `client`, `server` or `both`. Shown as a badge. |
| `builtOn` | | Upstream libraries it wraps, shown as "Built on". |
| `requires` | | Other kitr packages that must be added first. |
| `client` | | `true` if it needs a React frontend, so server-only projects refuse it. |
| `docs` | | The docs folder, relative to the package root. Include it in `files`. |

## Writing the summary

The summary is the first thing a beginner reads on the packages page, so it answers *what will this do for my app?* in plain words:

- **Good:** "Show rows of data with sorting, paging and filters that stay in the URL."
- **Not:** "TanStack Table v9 with URL-bound state." That only helps people who already know TanStack.

Put library names in `builtOn`, where they show as a separate note.

## Docs

```
docs/
├── index.md   # overview: what it's for, install, a working example, guides, configuration
└── api.md     # reference: every export, option and type
```

Each file starts with frontmatter:

```md
---
title: Stripe
description: Take card payments and subscriptions, with checkout pages you can restyle.
order: 1
---
```

The `description` of `index.md` must match the manifest `summary`. Follow the order the official packages use, so readers always know where to look:

1. **What it's for**, in two or three sentences, and when *not* to use it.
2. **Install**: the `kitr add` command and what it changes.
3. **A first working example** they can paste.
4. **Guides** for the common tasks.
5. **Configuration**: a table of every option with its default.
6. **Next steps**: the API page and the upstream docs.

Shell blocks that only contain `kitr` commands get the package-manager picker automatically. Link to other packages as `/packages/<name>`.

Follow [docs/STYLE.md](https://github.com/kitrjs/kitr/blob/main/docs/STYLE.md) in the repo for the full rulebook. Check the manifest and docs before publishing:

```sh
kitr package:check
```

## Live examples

Each `examples/<name>.tsx` becomes a live demo at the top of the package page, running in a sandboxed frame with a refresh button so readers can see what persists.

```tsx
// examples/checkout.tsx
export const meta = {
  title: 'Checkout',
  description: 'Pay with a test card. Reload to see the order is kept.',
}

export default function Example() {
  return <CheckoutButton priceId="price_test_123" />
}
```

Anything an example stores in the browser is namespaced to it, so examples never see each other's data.

## Setup with kitr add

To let `kitr add stripe` wire your package, export a setup module as `./kitr`:

```ts
// src/kitr.ts
import { definePackage } from '@kitr/core/package'

export default definePackage({
  name: 'stripe',
  requires: ['server'],
  questions: [
    { name: 'mode', type: 'select', message: 'Checkout mode?', default: 'hosted',
      options: [{ value: 'hosted' }, { value: 'embedded' }] },
  ],
  add(ctx) {
    ctx.provider.add('kitr-stripe/provider')
    ctx.config('stripe', `export default { mode: '${ctx.answers.mode}' }\n`)
    ctx.env.add({ STRIPE_SECRET_KEY: 'sk_test_...' })
    ctx.agents.add('stripe', '- Payments go through the `stripe` service ...')
  },
  remove(ctx) {
    ctx.provider.remove('kitr-stripe/provider')
    ctx.agents.remove('stripe')
  },
  commands: () => import('./commands'),   // `kitr stripe:sync-products`
  generators: { webhook: { description: 'A Stripe webhook handler', target, stub } },
})
```

Every question is also a flag (`kitr add stripe --mode embedded`), so agents and CI never see a prompt. `add` and `remove` get codemods for the files kitr owns: `kitrrc.ts` providers, `config/<name>.ts`, `package.json` scripts and dependencies, `.env.example`, `AGENTS.md`, `tsconfig.json`, `vite.config.ts` and the route table; `ctx.write` and `ctx.edit` cover anything else. Add `"setup": "./kitr"` to the manifest and build the module beside your runtime code. The full contract, with every `ctx` method, is in the [package contract](/docs/package-contract) reference.

## Publishing

```sh
npm publish
```

Use the `kitr-package` keyword. Community listings are on the way: a weekly sync will pick up packages with that keyword and list them under Community, with a health badge based on recent releases and the kitr versions they support.


# Package contract

Source: https://kitr.dev/docs/package-contract

Everything in kitr beyond the core is a package you add, and every package, official or not, plugs in the same way. A kitr package is an npm package with two additions: a static `kitr` block in `package.json`, read by the site, the registry and `kitr add --list` without executing anything, and a setup module exported as `<package>/kitr`, which the CLI loads from the installed package and runs on `kitr add`, `kitr remove`, `kitr doctor` and `kitr make:*`. Core knows no package by name: `kitr add @acme/anything` does exactly what `kitr add jobs` does.

## The setup module

```ts
// src/kitr.ts, published as the "./kitr" export
import { definePackage } from '@kitr/core/package'

export default definePackage({
  name: 'jobs',
  requires: ['server'],

  // Asked by `kitr add jobs`. Every question is also a flag (`--worker` / `--no-worker`),
  // so CI and agents never see a prompt; `when` makes a question depend on earlier answers.
  questions: [
    { name: 'worker', type: 'confirm', message: 'Run the job worker inside the server process?', default: true },
  ],

  // Codemods. Every call is idempotent and queued: the CLI writes once, installs once, formats once.
  add(ctx) {
    ctx.provider.add('@kitr/jobs/provider')
    ctx.config('jobs', jobsConfig(ctx.answers.worker !== false))   // writes config/jobs.ts
    ctx.write('server/jobs/example.ts', exampleJob)                 // skipped when it exists
    if (ctx.answers.worker === false) ctx.scripts.add('worker', 'kitr jobs:work')
    ctx.agents.add('jobs', '- Background work is a job in server/jobs/*.ts ...')
  },
  remove(ctx) {
    ctx.provider.remove('@kitr/jobs/provider')
    ctx.scripts.remove('worker', 'kitr jobs:work')
    ctx.agents.remove('jobs')
  },

  commands: () => import('./commands'),       // `kitr jobs:list`, `kitr jobs:work`
  generators: { job: { description: 'A job with a schema, retries and a schedule', target, stub } },
  doctor: (project) => [],                    // extra `kitr doctor` findings
  vite: { serverOnlyConfig: true },           // config/jobs.ts never reaches a browser bundle
})
```

The CLI installs the package itself and lists it in `kitrrc.ts` `packages`; `add` only does what is specific to the package. The service a package exposes is a container binding, declared the way every kitr package already does it: augment `ContainerBindings` in `@kitr/core` and bind it in the provider's `register`.

| Field | Type | What the CLI does with it |
| --- | --- | --- |
| `name` | string | The short name: `kitr add jobs`, `config/jobs.ts`, the `jobs:` command prefix |
| `kind` | `'package'` (default), `'platform'`, `'kit'` | A platform is added as `kitr add web site`; a kit is used by `kitr new --kit` |
| `requires` | string[] | Added first, in order, each with its own questions. Short names or full package names |
| `client` | boolean | Refused in a project with no React |
| `questions` | `Question[]` or `(project) => Question[]` | Asked on `add`; `--yes`, `CI` or no TTY takes the defaults |
| `add(ctx)` / `remove(ctx)` | codemods | Run with the answers; `--dry-run` prints the plan |
| `commands` | `() => import(...)` | A module of command objects (citty's shape), mounted as `kitr <name>`. The `<name>:` prefix is the convention; a core name or a name another package took is an error |
| `generators` | `Record<string, Generator>` | Mounted as `kitr make:<kind>`; the project's `stubs/<kind>.ts` overrides the stub |
| `doctor(project)` | `Finding[]` | Appended to `kitr doctor`. Pure: read, never write |
| `vite` | `{ serverOnlyConfig, optimizeDeps, plugin, provider }` | Read by `@kitr/vite` when it builds a web platform |
| `platform` | `{ factory, export, from }` | For `kind: 'platform'`: the `definePlatform` factory `kitrrc.ts` calls, and how it imports it |
| `kit` | `{ platforms, packages, components, files }` | For `kind: 'kit'`: what `kitr new --kit` adds and writes |
| `routes` | string | The module exporting this package's route-table extension |
| `eject` | `Record<string, string>` | Import rewrites `kitr eject all` prints |

### Questions

| Type | Flag | Answer |
| --- | --- | --- |
| `select` | `--driver redis` | one of `options` |
| `multiselect` | `--targets ios,android` | a list of `options` |
| `confirm` | `--worker` / `--no-worker` | boolean |
| `text` | `--port 4000` | string |

`when(answers, project)` skips a question (and its answer) when it returns false; `validate(value)` rejects a prompt or a flag with a message. `kitr add <pkg> --help` prints the questions as flags, read from the module, so the help is never stale.

### What `ctx` can do

`ctx` owns the wiring files and nothing else. Every call is idempotent.

| | |
| --- | --- |
| `ctx.deps.add('ioredis', { name: 'vite', dev: true })`, `ctx.deps.remove(...)` | `package.json` dependencies, installed once at the end |
| `ctx.provider.add('@kitr/jobs/provider')`, `.remove(...)` | the `providers` list in `kitrrc.ts` |
| `ctx.config('jobs', source)` | `config/jobs.ts`, skipped when it exists |
| `ctx.write(path, content, { overwrite })`, `ctx.unlink(path)` | any new file; delete a file kitr wrote |
| `ctx.edit(path, (mod, src) => ...)` | an existing file through magicast, or return replacement text |
| `ctx.scripts.add('worker', 'kitr jobs:work')`, `.remove(name, command?)` | `package.json` scripts |
| `ctx.env.add({ REDIS_URL: '...' })`, `ctx.env.schema('server', 'REDIS_URL', "e.url()")` | `.env.example` and `app/env.ts` |
| `ctx.agents.add('jobs', body)`, `.remove('jobs')` | a `## kitr: jobs` section in `AGENTS.md` |
| `ctx.tsconfig.addTypes(...)`, `.addLib(...)`, `.addInclude(...)`, `.addPaths({...})`, `.set(option, value)` | `tsconfig.json` |
| `ctx.vite.addPlugin('tailwind', '@tailwindcss/vite')` | `plugins` in `vite.config.ts`, when the file exists |
| `ctx.routes.extend('@kitr/api/routes')`, `.remove(...)` | the extensions list of the project's `defineRoutes([...])` call, in `directories.routeTable` (default `app/routes.ts`); created when missing |

The project facts it may read: `ctx.root`, `ctx.pm`, `ctx.pkg`, `ctx.rc` (packages, providers, directories, platforms), `ctx.isServerOnly`, `ctx.has('react')` (a dependency, present or queued), `ctx.hasPackage('server')` (in `kitrrc.ts`, or added earlier in this run), `ctx.exists(path)`, `ctx.read(path)`, and `ctx.answers`.

## The static block

```json
{
  "name": "@kitr/jobs",
  "exports": { ".": "./dist/index.js", "./provider": "./dist/provider.js", "./kitr": "./dist/kitr.js" },
  "kitr": {
    "name": "jobs",
    "title": "Jobs",
    "summary": "Run work in the background or on a schedule, with retries when it fails.",
    "category": "backend",
    "runsOn": "server",
    "requires": ["server"],
    "docs": "docs",
    "setup": "./kitr"
  }
}
```

`setup` says the package ships a setup module; the CLI looks for the `./kitr` export either way. `kitr package:check` validates the block, and the generated manifest table in the CLI (`pnpm manifests`) is what the site lists.

## How `kitr add` resolves a name

`jobs` means `@kitr/jobs`; anything with a scope or a slash is taken as written. When the package is not resolvable from the project, the CLI installs it first (`pnpm add @kitr/jobs`) and then loads its `kitr` module; with `--no-install` that is an error naming the flag. Inside this monorepo the module resolves from the CLI's own tree, which is how `kitr new --no-install` regenerates the examples. A package with no setup module falls back to the recipe of the same name inside the CLI, until every official package has moved its setup into its own code.

## Commands

A `commands` module exports plain command objects in citty's shape (`meta`, `args`, `run`); the kitr CLI mounts them next to its own. The `<name>:` prefix (`jobs:work`) is the convention, so a project with several packages never sees two meanings of one word; a bare name is allowed, and a collision with a core command or another package's command is an error at load time. Commands are loaded only when `kitr --help` runs or the word typed is not a core command, so an unrelated `kitr dev` pays nothing for them.

## Where the official setups are

| Package | Setup |
| --- | --- |
| `jobs`, `web` | `packages/<name>/src/kitr.ts` (the contract above) |
| every other package | `packages/cli/src/recipes*.ts` (legacy recipes, moving into their packages next) |


# CLI

Source: https://kitr.dev/docs/cli

`kitr` is installed with the `kitr` package (`pnpm add kitr`) and run as `pnpm kitr <command>` or `pnpm dlx kitr <command>`. Install it globally (`pnpm add -g kitr`) to type `kitr add ...` directly: inside a project that has its own `kitr`, the global binary hands over to that copy, so the version in `package.json` is always the one that edits your files (`KITR_GLOBAL=1` skips the handover). Every command runs from flags alone; nothing prompts.

## Project commands

| Command | What it does |
| --- | --- |
| `kitr new <dir> --kit <kit>` | Create a project. Base kits: `blank`, `app`, `fullstack`, `server`. Presets with real pages, controllers and tests: `saas` (sign-in, guarded app shell, projects CRUD, analytics, monitoring), `site` (SSR + prerender, SEO, i18n en/de, blog, newsletter controller), `realtime` (chat over typed channels), `desktop` (the app kit in an Electron shell with typed IPC), `mobile` (the app kit as a PWA and a Capacitor shell). `--platform site=web,api=server` replaces the kit's platforms; `--mode`, `--pwa`, `--runtime`, `--shell`, `--targets`, `--port` set their options. `--pm`, `--no-install`, `--no-git`, `--registry <url\|path>`, `--force`. |
| `kitr add <pkg...>` | Install the package(s), ask each one's questions (every question is a flag: `kitr add jobs --no-worker`; `--yes` takes the defaults), register providers in `kitrrc.ts`, write `config/<pkg>.ts` and stubs, update `AGENTS.md`. Follows `requires` (adding `api` adds `server` and `logger`; adding `router` adds `react`). Any npm package that ships a kitr setup module works (`kitr add @acme/stripe`); see [package-contract.md](/docs/package-contract). `kitr add <pkg> --help` prints its questions. `--dry-run`, `--no-install`. |
| `kitr <pkg>:<cmd>` | Commands the installed packages contribute (`kitr jobs:list`, `kitr jobs:work`). `kitr --help` lists them after the core commands. |
| `kitr add <type> <name> [--option value]` | Adds a platform (`web`, `server`, `desktop`, `mobile`): `kitr add web admin --mode spa`, `kitr add desktop app --shell tauri`. Installs the platform package and the packages it needs, writes `platforms.<name>` into `kitrrc.ts`, scaffolds `platforms/<name>/` for native shells and adds the `dev`/`build`/`start` scripts. See [platforms.md](/docs/platforms). |
| `kitr remove <pkg...>` | Reverse of `add`: unregisters the provider and package, deletes `config/<pkg>.ts`, removes dependencies, then lists files that still import it. |
| `kitr doctor` | Checks `kitrrc.ts` against `package.json`, providers that resolve, missing config files, direct upstream imports where a `kitr/*` entry exists, server-only projects that pull React, version drift from the tested set. `--json`, `--strict`. Exit code 1 on errors. |
| `kitr info` | JSON summary: version, package manager, packages, providers, platforms, directories, server-only or not. |
| `kitr upgrade [--to x.y.z] [--majors]` | Moves `kitr` and every `@kitr/*` to one version and aligns upstream libraries with the versions that release was tested with. Major bumps are listed, not applied, unless `--majors`. |

## Platforms

| Command | What it does |
| --- | --- |
| `kitr dev [names...]` | Runs every platform in `kitrrc.ts`, or the named ones, in development: `kitr dev`, `kitr dev site api`, `kitr dev site --port 4000`. |
| `kitr build [names...]` | Production builds into `dist/<name>/`. |
| `kitr start [names...]` | Serves the builds (`kitr serve` is an alias). |
| `kitr platforms [types\|scaffold <name>\|remove <name>]` | Lists platforms and their effective options; lists the available types; rewrites a platform's scaffold; removes one from `kitrrc.ts`. |
| `kitr config <name> [option] [value] [--unset]` | Reads or sets one platform option in `kitrrc.ts`, validated against the platform's schema: `kitr config site port 4000`. `KITR_<NAME>_<OPTION>` overrides any option at run time. |

## Generators

`kitr make:<kind> <name>` writes one file from a stub. `--force` overwrites. Stubs can be customised per project: `kitr eject stub <kind>` copies it to `stubs/<kind>.ts`, and `make:*` prefers the ejected version.

| Command | Writes |
| --- | --- |
| `make:route projects/index` | `app/routes/projects/index.tsx` with route path `/projects/` |
| `make:route projects/:id` | `app/routes/projects/$id.tsx` |
| `make:query projects/list` | `app/actions/projects/list.ts` (`defineQuery('projects.list', ...)`) |
| `make:mutation projects/create` | `app/actions/projects/create.ts` (`defineMutation('projects.create', ...)`) |
| `make:controller projects [--resource]` | `server/controllers/projects_controller.ts` (index/show/store/update/destroy with `--resource`) |
| `make:middleware audit` | `app/middleware/audit.ts` |
| `make:channel chat` | `app/channels/chat.ts` (`defineChannel`) |
| `make:store cart` | `app/stores/cart.ts` (`createKitrStore`) |
| `make:form project` | `app/components/forms/project_form.tsx` |
| `make:queries projects` | `app/features/projects/queries.ts` (keys, queries, mutation with effects) |
| `make:provider analytics` | `app/providers/analytics_provider.ts` |
| `make:job send_digest` | `server/jobs/send_digest.ts` (`defineJob` with a schema and retries; list it in `config/jobs.ts`). Contributed by the `jobs` package: present once it is added |
| `make:mail welcome` | `server/mail/welcome.tsx` (`defineMail` with a preview) |
| `make:service billing` | `server/services/billing_service.ts` (a class to bind in a provider) |
| `make:validator project` | `app/validators/project.ts` (create/update zod schemas) |
| `make:test projects` | `test/projects.test.ts`, run by the project's vitest (`createTestApp`) |
| `make:component user-card` | `app/components/user-card.tsx` |
| `make:hook toggle` | `app/hooks/use-toggle.ts` |
| `make:exception payment_failed` | `app/exceptions/payment_failed_error.ts` (a `KitrError` subclass) |

## Components

| Command | What it does |
| --- | --- |
| `kitr ui add <name...>` | Copies components from a shadcn-compatible registry into `app/components/ui` (and pages into `app/routes`), resolving `registryDependencies` and installing npm dependencies. `--registry`, `--overwrite`. |
| `kitr ui list` | Lists the registry's items. |

The default registry is kitr's own (`registry/dist` in this repo). Point `--registry`, `config/theme.ts` or `KITR_REGISTRY` at any other shadcn-format registry, including a local folder.

## API and server

| Command | What it does |
| --- | --- |
| `kitr api:sync` | Loads the routes file (`server/routes.ts`), writes `openapi.json` (OpenAPI 3.1; schemas from zod, valibot or arktype when present) and `routes.gen.ts`, a plain route table for clients that cannot import the server. `--file`, `--out`. |
| `kitr routes:list` | Prints the route table: method, path, name. |
| `kitr css:types` | Writes a `.d.ts` beside every `*.module.css`. `--check` fails when stale. |

## Type generation

`kitr types` writes the project's generated types under `.kitr/`, a folder that is ignored by git, included in `tsconfig.json` and reachable as `#kitr/*`. `kitr dev` and `kitr build` run it first, the Vite plugin reruns the generator whose files changed while the dev server runs, `kitr new` and `kitr add` run it after installing, and the kits' `typecheck` script is `kitr types && tsc --noEmit`.

| Command | What it does |
| --- | --- |
| `kitr types` | Runs every generator and writes the files whose content changed. |
| `kitr types --check` | Lists stale files and exits non-zero instead of writing. For CI. |
| `kitr types --watch` | Keeps running and regenerates on change, for editors without the dev server. |
| `kitr types --only actions` | Runs one generator by name. |

| Generator | From | Writes |
| --- | --- | --- |
| `platforms` (built in) | `platforms` in `kitrrc.ts` | `.kitr/platforms.d.ts`: the `KitrPlatforms` augmentation, so `app.platform` and `usePlatform().name` are the project's names. |
| `actions` (`@kitr/actions`) | `app/actions/**/*.ts` | `.kitr/actions.ts`: `operations` and `actions` maps and the `Operations` augmentation behind `useQuery('projects.list')`. |

A package adds a generator by exporting one from a `./types` subpath and naming it in its manifest:

```ts
// packages/<name>/src/types.ts
import { defineTypes } from '@kitr/core'

export default defineTypes({
  name: 'channels',
  watch: (rc) => [`${rc.directories.app ?? 'app'}/channels/**/*.ts`],
  generate: (ctx) => [{ file: 'channels.d.ts', content: render(ctx.glob('app/channels', '**/*.ts')) }],
})
```

```json
{ "kitr": { "types": "./types" }, "exports": { "./types": "./dist/types.js" } }
```

`generate` is pure: it returns `{ file, content }` pairs relative to `.kitr/` and the runner writes them. `watch` says which files re-run it in dev. `kitr doctor` warns when `.kitr/` is stale.

## Leaving kitr

`kitr eject stubs` copies every generator stub. `kitr eject all` also prints the import rewrites that remove kitr entirely: each `kitr/*` entry maps to the upstream package it re-exports.


# Platforms

Source: https://kitr.dev/docs/platforms

Where an app runs is a **platform**: a named entry in `kitrrc.ts` built by a factory from a platform package. The core knows only the contract (`definePlatform` in `@kitr/core`); each package owns its options, its scaffold, its dev server and its build.

```ts
// kitrrc.ts
import { defineKitrConfig } from 'kitr/app'
import { web } from 'kitr/web'
import { server } from 'kitr/server'
import { desktop } from 'kitr/desktop'

export default defineKitrConfig({
  platforms: {
    site: web({ mode: 'ssr', pwa: true }),
    api: server({ runtime: 'node', port: 3001 }),
    app: desktop({ shell: 'tauri', title: 'My App' }),
  },
  packages: [...],
  providers: [...],
})
```

Names are yours. One project can hold several platforms of the same type (`admin: web({...})`, `www: web({...})`), and every command addresses them by name.

| Type | Package | Factory | What it builds |
| --- | --- | --- | --- |
| `web` | `@kitr/web` | `web()` from `kitr/web` | A browser app through TanStack Start: `static` (prerendered pages), `spa`, or `ssr`. `pwa: true` adds the manifest and service worker. |
| `server` | `@kitr/server` | `server()` from `kitr/server` | The h3 server in `server/main.ts` on Node, Bun, Deno or Cloudflare Workers. |
| `desktop` | `@kitr/desktop` | `desktop()` from `kitr/desktop` | A Tauri or Electron shell around the SPA build. Native project in `platforms/<name>/`. |
| `mobile` | `@kitr/mobile` | `mobile()` from `kitr/mobile` | A Capacitor shell for iOS and Android. Native project in `platforms/<name>/`. |

## Commands

| Command | What it does |
| --- | --- |
| `kitr dev [names...]` | Starts every platform (or the named ones) in parallel: Vite for `web`, `tsx watch` / `bun --watch` / `wrangler dev` for `server`, the Tauri or Electron dev window for `desktop`, Capacitor live reload for `mobile`. |
| `kitr build [names...]` | Production builds, in order. Web platforms land in `dist/<name>/` (`client/` and, for SSR, `server/server.js`). |
| `kitr start [names...]` | Serves the builds: srvx for SSR and static sites, the compiled server for `server`. |
| `kitr add <type> <name> [--option value]` | Adds a platform: installs the package, writes `platforms.<name>` into `kitrrc.ts`, adds the packages the platform needs (`router` for `web`, `router platform storage` for `desktop` and `mobile`, `server` for `server`), scaffolds its files and the `dev`/`build`/`start` scripts. `kitr add web admin --mode spa --port 3002`. |
| `kitr platforms` | Lists the platforms and their effective options. `kitr platforms types` lists the available types, `kitr platforms scaffold <name>` rewrites a platform's files, `kitr platforms remove <name>` takes it out of `kitrrc.ts`. |
| `kitr config <name> [option] [value]` | Reads or sets one option in `kitrrc.ts`, validated against the platform's option schema: `kitr config site port 4000`, `kitr config api runtime bun`, `kitr config site pwa --unset`. |

Every option can be overridden at run time without touching the file: `KITR_SITE_PORT=4000 kitr dev site`, or `kitr dev site --port 4000`. The name is upper-cased with non-alphanumerics turned into `_`.

`kitr doctor` runs each platform's own checks (the Rust toolchain for Tauri, Xcode and Android Studio for Capacitor, `wrangler` for Workers).

## Options

**web** (`@kitr/web`)

| Option | Default | Description |
| --- | --- | --- |
| `mode` | `spa` | `static`: prerender every route to HTML. `spa`: one shell, client routing. `ssr`: render on request through TanStack Start. |
| `port` | `3000` | Dev and production port. |
| `host` | | Bind address (localhost in dev, `0.0.0.0` in production). |
| `pwa` | `false` | `true` or `{ name, shortName, themeColor, ... }`: web manifest, service worker (vite-plugin-pwa, autoUpdate), `useInstallPrompt`, `useServiceWorker` from `kitr/web/client`. |
| `base` | `/` | Public base path. |
| `open` | `false` | Open the browser on `kitr dev`. |

Prerendering, the sitemap and `robots.txt` come from `config/seo.ts` (`kitr add seo`).

**server** (`@kitr/server`)

| Option | Default | Description |
| --- | --- | --- |
| `runtime` | `node` | `node`, `bun`, `deno` or `workers` (Cloudflare, via `wrangler.toml`). |
| `port` | `3001` | |
| `host` | | |
| `entry` | `server/main.ts` | `createServer({...})` plus routes and realtime. A React project with a web platform also gets `app/routes/api.$.ts`, which mounts the same server inside TanStack Start. |

**desktop** (`@kitr/desktop`)

| Option | Default | Description |
| --- | --- | --- |
| `shell` | `tauri` | `tauri` (Rust, small binary, `platforms/<name>/src-tauri`) or `electron` (electron-vite, `platforms/<name>/{main,preload,ipc}.ts`). |
| `port` | `3200` | Dev server the window loads. |
| `title`, `width`, `height`, `minWidth`, `minHeight` | | Window. |
| `appId` | | Bundle identifier. |
| `devtools` | `true` | Open devtools in dev. |

`kitr/desktop/client` tells which shell is running (`isTauri`, `isElectron`, `desktopShell`); `kitr/desktop/tauri` has `defineCommands`, `commandQuery`, `commandMutation` and `useTauriEvent`, `kitr/desktop/electron` the typed IPC bridge with `kitr/desktop/electron-main` and `kitr/desktop/electron-preload` for the other two processes. `kitr/desktop/provider` registers the `platform` and `storage` drivers for the shell in use.

**mobile** (`@kitr/mobile`)

| Option | Default | Description |
| --- | --- | --- |
| `targets` | `ios,android` | Native projects; `kitr dev`/`kitr build` run `cap add <target>` the first time and `--target ios|android` picks one. |
| `appId`, `appName` | | Bundle identifier and display name. |
| `scheme` | | Custom URL scheme for deep links. |
| `port` | `3100` | Dev server for live reload on the device. |

`kitr/mobile/provider` registers the Capacitor drivers; `kitr/platform/react` (`usePlatform`, `useAppState`, `useBackButton`, `useDeepLink`, `useSafeArea`) and `kitr/storage` then answer the same way in the browser and in the shell.

## Layout

```
app/                 # routes, components, features, channels: shared by every UI platform
server/
  main.ts            # the server platform entry (createServer + routes + realtime)
  routes.ts          # defineRoutes(...)
  controllers/
  realtime.ts        # createRealtimeServer({ channels })
config/              # one file per package (config/seo.ts, config/realtime.ts, config/theme.ts, ...)
platforms/
  app/               # desktop: src-tauri/ or the Electron main/preload sources
  phone/             # mobile: capacitor.config.ts, ios/, android/
dist/<name>/         # build output per platform
kitrrc.ts
```

## Writing a platform package

```ts
import { definePlatform } from 'kitr/app'

export const kiosk = definePlatform<{ port?: number }>(
  {
    type: 'kiosk',
    description: 'Fullscreen Chromium on a Raspberry Pi',
    describe: { port: { type: 'number', default: 3300, description: 'Dev server port' } },
    requires: ['router', 'platform'],       // recipes `kitr add kiosk <name>` runs first
    provider: '@acme/kitr-kiosk/provider',  // registered in kitrrc.ts providers
  },
  (options) => ({
    dependencies: { chromium: '^1.0.0' },
    async scaffold(ctx) { await ctx.write('kiosk.json', '{}') },
    async dev(ctx) { await ctx.exec('vite', ['--port', String(options.port)]) },
    async build(ctx) { await ctx.exec('vite', ['build', '--outDir', ctx.dir('dist')]) },
    async start(ctx) { await ctx.exec('chromium', ['--kiosk', `http://localhost:${options.port}`]) },
    async doctor(ctx) { return [] },
    agents: 'Run `kitr dev kiosk` and open the window on the Pi.',
  }),
)
```

`ctx` carries the platform name, the project root, the resolved options, the package manager, the other platforms, the flags from the command line, an abort signal and `log`, `run` and `exec` helpers that resolve `node_modules/.bin`. `kitr/vite` reads `import.meta.env.KITR_PLATFORM` and `KITR_PLATFORM_TYPE` so app code can branch per platform at build time.


# Packages

Source: https://kitr.dev/docs/packages

Every app starts with `@kitr/core` and the `kitr` CLI. Everything else, the router included, is added with `kitr add <name>`. "Client" packages are refused in server-only projects; the rest work anywhere.

## Capabilities

| Name | Package | Scope | Needs | Provides |
| --- | --- | --- | --- | --- |
| `react` | `@kitr/react` | client | | `<KitrProvider>`, `useApp()`, `useService()`, `useConfig()`. Added by `router`. |
| `router` | `@kitr/router` | client | react | TanStack Router, `createKitrRouter`, `requireAuth()`, `can()`, default pending/error/404 routes, `app/router.tsx` and `app/client.tsx`. Every UI platform needs it. |
| `query` | `@kitr/query` | client | | TanStack Query, `defineQuery`/`defineMutation`/`defineSubscription`, cache effects, `useSubscription`, a provider with sane defaults (30s stale, no retry on 4xx). |
| `http` | `@kitr/http` | client | query | ky with bearer auth, refresh-once on 401, kitr/Adonis error normalisation; `httpQuery`/`httpMutation` contracts. |
| `forms` | `@kitr/forms` | client | | React Hook Form, `useSchemaForm(schema)` for any Standard Schema library, `<Form>` that maps server `fieldErrors`, headless `<FormField>`. |
| `table` | `@kitr/table` | client | | TanStack Table v9 (feature-sliced), `dataTableFeatures`, `useUrlTableState` for shareable sort/page/filter URLs. |
| `state` | `@kitr/state` | client | | Zustand, `createKitrStore` returning `[useStore, StoreProvider, store]` with per-request stores on the server. |
| `tailwind` | `@kitr/tailwind` | client | | Tailwind v4 via Vite, `cn()`, the preset that exposes kitr tokens as `@theme` so `bg-background` and friends work. |
| `theme` | `@kitr/theme` | client | | Design tokens (`defineTokens`, oklch defaults with a dark set, `app/styles/tokens.css`), `ThemeProvider`/`useTheme` (system/light/dark, cookie for SSR, `meta[name=theme-color]`), `toast` over sonner, `cva`/`clsx`, and the registry settings `kitr ui add` reads from `config/theme.ts`. |
| `auth` | `@kitr/auth` | client | | `createAuth(adapter)` with token, Better Auth and custom adapters, `defineAbilities`, router guards, `useAuth`/`useCan`; `kitr/auth/server` middleware for the API. |
| `logger` | `@kitr/logger` | any | | Structured logger, levels, children, request ids, pretty in dev and JSON in production. |
| `server` | `@kitr/server` | any | logger | h3 server with the kitr app lifecycle, request-scoped container, health route, graceful shutdown. Standalone via srvx, or a `fetch` handler inside Start. `kitr/server/platform` is the `server()` platform factory. |
| `api` | `@kitr/api` | any | server | Adonis-style router (groups, resources, middleware) in `server/routes.ts`, controllers in `server/controllers/` with `static validation`, typed client with no codegen, OpenAPI. |
| `actions` | `@kitr/actions` | client | server, query | `defineQuery` and `defineMutation` over Start server functions: input schema, middleware, one error shape, cache effects. `kitr types` registers every name, so `useQuery('projects.list')` is typed. |
| `seo` | `@kitr/seo` | client | | `seo()` head tags, `jsonLd()`, `ssrRoute()`, `cacheHeaders()`, `robotsTxt()`; `config/seo.ts` drives the web platform's prerender list and sitemap. |
| `realtime` | `@kitr/realtime` | any | server | Typed channels over one of three transports chosen in `config/realtime.ts`: `ws` (partysocket client, crossws server), `socket.io` (rooms), `sse` (EventSource plus a POST control channel). Events apply cache effects; `kitr/realtime/react` has `useChannel`. |
| `db` | `@kitr/db` | any | server | `defineDb({ connect, disconnect })` so any ORM joins the lifecycle and is available as `ctx.db`. |
| `testing` | `@kitr/testing` | any | | Vitest config, `createTestApp`, `createTestClient(server)`; `kitr/testing/react` for `renderWithKitr`. |
| `mocks` | `@kitr/mocks` | client | | MSW handlers from kitr route tables and contracts, for dev without a backend and for tests. |
| `i18n` | `@kitr/i18n` | client | | react-i18next, typed keys from your resource files, locale detection. |
| `analytics` | `@kitr/analytics` | client | | `page`/`track`/`identify` behind one API with Google Analytics, Plausible, PostHog and console adapters; page views from the router; queue-until-consent; typed event map. |
| `monitoring` | `@kitr/monitoring` | any | | `captureException`, breadcrumbs, user context behind one API; Sentry and console reporters; window handlers, an error boundary, `reportErrors` h3 middleware. Drops expected 4xx by default. |
| `offline` | `@kitr/offline` | client | query, storage | Persists successful queries and paused mutations to the app's storage driver, restores them before the first render and replays mutations on reconnect; `useOffline()` for `{ online, pending, restored }`. |
| `flags` | `@kitr/flags` | any | | `defineFlags` with typed defaults, ordered providers (env, percentage rollout, OpenFeature for any vendor), per-request `resolveFlags` on the server embedded with `<FlagsScript />`, `useFlag()` in components. |
| `consent` | `@kitr/consent` | client | storage | One consent record by category in a cookie the server can read; analytics and (optionally) monitoring wait for their category; `useConsent()` drives the banner. |
| `secure-storage` | `@kitr/secure-storage` | any | storage | Secrets in the OS vault (Keychain, Keystore, safeStorage) with an AES-GCM web fallback; `defineSecureItem` for typed, validated items; `useSecureItem()`. |
| `files` | `@kitr/files` | client | platform | `open`/`pick`/`save` with native dialogs on desktop and mobile, the File System Access API in the browser and a download fallback; `useFileDialogs()`, `useDropFiles()`. |
| `notifications` | `@kitr/notifications` | client | platform | Permission, `show`, `schedule`, `cancel` and a tap listener that carries the page to open; web Notification API or the platform's driver. |
| `native` | `@kitr/native` | client | platform | Clipboard, share sheet, haptics, geolocation, camera and biometrics, each a separate capability with a web driver and a `supported` flag; `useClipboard()`, `useShare()`, `useGeolocation()`. |
| `updater` | `@kitr/updater` | client | platform | One `check`/`apply` state machine over the service worker on the web and the platform updaters on desktop and mobile; `useUpdate()` for the banner. |
| `cache` | `@kitr/cache` | any | server | `remember`, tags and `cached()` over a `CacheDriver` (in-memory shipped, Redis-shaped interface), with in-flight de-duplication. |
| `shield` | `@kitr/shield` | any | server | Security headers, CORS, per-IP rate limiting with RateLimit-* headers and double-submit CSRF as h3 middlewares; `shield(server)` reads `config/shield.ts`. |
| `mail` | `@kitr/mail` | any | server | React email templates (`defineMail`), log, Resend and SMTP transports, text alternatives, and `/_kitr/mail` previews in development. |
| `jobs` | `@kitr/jobs` | any | server | `defineJob` with a payload schema, retries with backoff, timeouts and cron or interval schedules; an in-process worker over a `JobsDriver` (in-memory shipped). |
| `uploads` | `@kitr/uploads` | any | | Client `upload()` with progress and typed errors plus `useUpload()`; server `receive()`/`mount()` that parses multipart per size and type rules into a disk or custom driver. |
| `platform` | `@kitr/platform` | client | | One API for where the app runs: `platform()`, `isNative()`, `perPlatform()`, and the hooks `usePlatform`, `useOnline`, `useAppState`, `useBackButton`, `useDeepLink`, `useSafeArea`. A driver registry the desktop and mobile packages fill; the browser is the default driver. |
| `storage` | `@kitr/storage` | any | | `defineStorage` (typed local/session items with schema, version+migrate, ttl, cross-tab sync) and `defineCookie` readable on both sides; `useStorage`/`useCookie` hydration-safe hooks; `cookies(event)` on the server. Native drivers (Tauri store, Electron IPC, Capacitor Preferences) come from the platform packages. |
| `devtools` | `@kitr/devtools` | client | | The development overlay: App, Router, Query, Auth, Storage, Platform, Errors, Analytics and Log panels, a command palette, and a hub any package logs to. Providers add panels with a `devtools()` method. Dropped from production builds by the Vite plugin. |

Always present: `@kitr/core` (app, container, providers, config, env, errors, contracts, validation, the `definePlatform` contract), `@kitr/vite` in projects with a UI platform, `@kitr/cli` through the `kitr` binary.

## Platforms

Platforms are packages too, added with `kitr add <type> <name>` and configured in `kitrrc.ts` under `platforms`. See [platforms.md](/docs/platforms).

| Type | Package | Entry points | Needs |
| --- | --- | --- | --- |
| `web` | `@kitr/web` | `kitr/web` (`web()`), `kitr/web/client` (`useInstallPrompt`, `useServiceWorker`), `kitr/web/vite` | router |
| `server` | `@kitr/server` | `kitr/server` (`server()` beside `createServer`), `kitr/server/platform` | server |
| `desktop` | `@kitr/desktop` | `kitr/desktop` (`desktop()`), `kitr/desktop/client`, `kitr/desktop/tauri`, `kitr/desktop/electron`, `kitr/desktop/electron-main`, `kitr/desktop/electron-preload`, `kitr/desktop/provider` | router, platform, storage |
| `mobile` | `@kitr/mobile` | `kitr/mobile` (`mobile()`), `kitr/mobile/client`, `kitr/mobile/provider` | router, platform, storage |

## Devtools

`kitr add devtools` (in every React kit by default) mounts a bottom panel in development: ctrl/cmd+shift+K toggles it, ctrl/cmd+shift+P opens a command palette with every package's actions. Each package contributes its own panel through the provider's `devtools(app)` method, and logs through `getDevtools(app)?.log(channel, label, data)`, which is `null` in production. Out of the box: App (mode, providers, container, config, env), Router (location, matches, loader data, navigation log), Query (cache with invalidate/refetch/remove), Auth (session, sign out), Storage (local/session/cookies with remove), Platform (type, OS, drivers, app state), Errors (captured exceptions and breadcrumbs), Analytics (events, enable/disable) and Log (http requests, logger records, every channel). The kitr Vite plugin leaves the provider out of production builds, so nothing of it ships.

## Kits

| Kit | Platforms | Packages |
| --- | --- | --- |
| `blank` | `site: web({ mode: 'spa' })` | router, query |
| `app` | `site: web({ mode: 'spa' })` | router, query, http, forms, table, state, tailwind, theme, auth, storage, mocks, testing, devtools, plus eleven registry components (including `icon`, Hugeicons stroke-rounded) |
| `fullstack` | `site: web({ mode: 'ssr' })`, `api: server()` | the app kit plus logger, server, seo, actions, api, realtime |
| `server` | `api: server()` | logger, server, api, db, realtime, testing. No React. |
| `saas` | `site` (ssr), `api` | the fullstack set with analytics and monitoring; sign-in, guarded shell, projects CRUD, tests |
| `site` | `site` (ssr), `api` | query, forms, tailwind, theme, i18n, storage, analytics, seo, api, testing, devtools; prerendered pages, blog, newsletter |
| `realtime` | `site` (ssr), `api` | query, forms, tailwind, theme, storage, seo, api, realtime, testing, devtools; chat over typed channels |
| `desktop` | `site: web({ mode: 'spa' })`, `app: desktop({ shell: 'electron' })` | the app kit plus platform; native dialogs over typed IPC |
| `mobile` | `site: web({ mode: 'spa', pwa: true })`, `phone: mobile()` | the app kit plus platform; installable PWA and the Capacitor shell |

`kitr new <dir> --platform admin=web,api=server --mode spa --runtime bun` replaces a kit's platforms; `--shell`, `--targets`, `--pwa` and `--port` set the first platform's options.

## Roadmap

Later: local-db, payments, better-auth, ai, push, sync, search, media, admin, workflow, audit, tenancy, cms, graphql, commerce. Each lands as a package with a recipe, docs and a `make:*` command where one fits.


# Entry points

Source: https://kitr.dev/docs/entry-points

Every `kitr/*` import maps to one `@kitr/*` package. The umbrella `kitr` package is a set of one-line re-exports plus the CLI binary; it has no code of its own.

## The rules

1. **Re-export, never re-implement.** `kitr/router` does `export * from '@tanstack/react-router'`. Nothing upstream is renamed, wrapped or hidden. If a TanStack doc page says `import { Link } from '@tanstack/react-router'`, `import { Link } from 'kitr/router'` is the same thing.
2. **Add beside, never change.** kitr's additions are new names (`createKitrRouter`, `defineQuery`, `useUrlTableState`). The one exception is documented in [departures.md](/docs/departures): `kitr/forms` exports its own `Form` and re-exports React Hook Form's as `RhfForm`.
3. **Providers are subpaths.** `kitr/query/provider`, `kitr/http/provider`, `kitr/theme/provider`, `kitr/auth/provider` export a provider as `default`, so `kitrrc.ts` can lazy-import them without pulling the rest of the package into the boot path.
4. **Server entries never import React.** `kitr/server`, `kitr/api`, `kitr/logger`, `kitr/realtime/server`, `kitr/realtime/socket.io/server`, `kitr/realtime/sse/server`, `kitr/auth/server`, `kitr/db` and `kitr/testing` are safe in a Node-only project. `kitr/testing/react` is where `renderWithKitr` lives.
5. **Platforms are packages.** `kitr/web`, `kitr/server`, `kitr/desktop` and `kitr/mobile` each export a factory built with `definePlatform` from `@kitr/core`. The core knows the contract, never a platform.
6. **Optional peers.** `kitr` lists every `@kitr/*` package as an optional peer. `kitr add <name>` installs the ones you use; importing an entry whose package is missing fails at build time with a clear module-not-found, not at runtime.

## One exception you will hit

In route files, import `createFileRoute`, `createLazyFileRoute` and the root-route creators from `@tanstack/react-router` directly:

```ts
import { createFileRoute } from '@tanstack/react-router'
import { Link, Outlet } from 'kitr/router'
```

TanStack's route generator rewrites that specific import in every route file and only recognises `@tanstack/react-router` as its source. Everything else in the file comes from `kitr/router`. `kitr doctor` knows about this exception and does not flag it.

## Reading the map

| Entry | Package | React |
| --- | --- | --- |
| `kitr`, `kitr/app` | `@kitr/core` | no |
| `kitr/env` | `@kitr/core` | no |
| `kitr/react` | `@kitr/react` | yes |
| `kitr/router` | `@kitr/router` | yes |
| `kitr/query`, `kitr/query/provider` | `@kitr/query` | yes |
| `kitr/http`, `kitr/http/provider` | `@kitr/http` | no (provider is framework-neutral) |
| `kitr/forms` | `@kitr/forms` | yes |
| `kitr/table` | `@kitr/table` | yes |
| `kitr/state` | `@kitr/state` | yes |
| `kitr/tailwind`, `kitr/tailwind/vite`, `kitr/tailwind/preset.css` | `@kitr/tailwind` | no |
| `kitr/theme`, `kitr/theme/provider`, `kitr/theme/styles.css` | `@kitr/theme` | yes |
| `kitr/theme/server` | `@kitr/theme` | no |
| `kitr/logger` | `@kitr/logger` | no |
| `kitr/server`, `kitr/server/platform` | `@kitr/server` | no |
| `kitr/api`, `kitr/api/client` | `@kitr/api` | no |
| `kitr/actions` | `@kitr/actions` | yes (TanStack Start) |
| `kitr/seo` | `@kitr/seo` | no |
| `kitr/realtime`, `kitr/realtime/client`, `kitr/realtime/socket.io`, `kitr/realtime/sse` | `@kitr/realtime` | no |
| `kitr/realtime/server`, `kitr/realtime/socket.io/server`, `kitr/realtime/sse/server` | `@kitr/realtime` | no |
| `kitr/realtime/react` | `@kitr/realtime` | yes |
| `kitr/auth`, `kitr/auth/provider` | `@kitr/auth` | hooks need React; `createAuth` does not |
| `kitr/auth/server` | `@kitr/auth` | no |
| `kitr/db` | `@kitr/db` | no |
| `kitr/testing` | `@kitr/testing` | no |
| `kitr/testing/react` | `@kitr/testing` | yes |
| `kitr/mocks` | `@kitr/mocks` | no |
| `kitr/i18n`, `kitr/i18n/provider` | `@kitr/i18n` | yes |
| `kitr/analytics`, `kitr/analytics/provider` | `@kitr/analytics` | no |
| `kitr/analytics/react` | `@kitr/analytics` | yes |
| `kitr/monitoring`, `kitr/monitoring/provider`, `kitr/monitoring/server` | `@kitr/monitoring` | no |
| `kitr/platform`, `kitr/platform/provider` | `@kitr/platform` | no |
| `kitr/platform/react`, `kitr/platform/devtools` | `@kitr/platform` | yes |
| `kitr/offline`, `kitr/offline/provider` | `@kitr/offline` | no |
| `kitr/offline/react` | `@kitr/offline` | yes |
| `kitr/flags`, `kitr/flags/provider`, `kitr/flags/server` | `@kitr/flags` | no |
| `kitr/flags/react` | `@kitr/flags` | yes |
| `kitr/consent`, `kitr/consent/provider` | `@kitr/consent` | no |
| `kitr/consent/react` | `@kitr/consent` | yes |
| `kitr/secure-storage`, `kitr/secure-storage/provider` | `@kitr/secure-storage` | no |
| `kitr/secure-storage/react` | `@kitr/secure-storage` | yes |
| `kitr/files`, `kitr/files/provider` | `@kitr/files` | no |
| `kitr/files/react` | `@kitr/files` | yes |
| `kitr/notifications`, `kitr/notifications/provider` | `@kitr/notifications` | no |
| `kitr/notifications/react` | `@kitr/notifications` | yes |
| `kitr/native`, `kitr/native/provider` | `@kitr/native` | no |
| `kitr/native/react` | `@kitr/native` | yes |
| `kitr/updater`, `kitr/updater/provider` | `@kitr/updater` | no |
| `kitr/updater/react` | `@kitr/updater` | yes |
| `kitr/cache`, `kitr/cache/provider` | `@kitr/cache` | no |
| `kitr/shield`, `kitr/shield/provider` | `@kitr/shield` | no |
| `kitr/mail`, `kitr/mail/provider` | `@kitr/mail` | templates are React elements; sending needs react-dom/server |
| `kitr/jobs`, `kitr/jobs/provider` | `@kitr/jobs` | no |
| `kitr/uploads`, `kitr/uploads/server`, `kitr/uploads/provider` | `@kitr/uploads` | no |
| `kitr/uploads/react` | `@kitr/uploads` | yes |
| `kitr/storage`, `kitr/storage/provider`, `kitr/storage/server` | `@kitr/storage` | no |
| `kitr/storage/react` | `@kitr/storage` | yes |
| `kitr/devtools`, `kitr/devtools/provider` | `@kitr/devtools` | no (`kitr/devtools/ui` is React) |
| `kitr/web`, `kitr/web/vite` | `@kitr/web` | no (CLI and build time) |
| `kitr/web/client`, `kitr/web/provider` | `@kitr/web` | hooks need React |
| `kitr/desktop`, `kitr/desktop/electron-main`, `kitr/desktop/electron-preload` | `@kitr/desktop` | no |
| `kitr/desktop/client`, `kitr/desktop/tauri`, `kitr/desktop/electron`, `kitr/desktop/provider` | `@kitr/desktop` | `useTauriEvent` needs React |
| `kitr/mobile` | `@kitr/mobile` | no (CLI) |
| `kitr/mobile/client`, `kitr/mobile/provider` | `@kitr/mobile` | no |
| `kitr/vite` | `@kitr/vite` | no (build time) |


# Design decisions

Source: https://kitr.dev/docs/departures

The implementation follows the "Kitr — Framework Design Plan". These are the places where it deliberately differs, and why.

## Typed API client without codegen

The plan had `kitr api:sync` generate a typed client. Instead the router accumulates route types as you chain calls, `typeof routes.$types` is the whole contract, and `createApiClient<AppRoutes>()` is a `Proxy` that resolves names at runtime from a route table. Controllers contribute their output types through `[Controller, 'method']` tuples and their input types through `static validation`. `api:sync` still runs, but it only emits `openapi.json` and a plain route table for consumers that cannot import the server. No generated TypeScript, nothing to forget to regenerate.

## `@kitr/core` has zero React

The plan put the provider `wrap()` hook in core. Core now declares `KitrNodeTypes`, an interface `@kitr/react` augments with `ReactNode`. Core's `wrap` is typed against that, so the same core serves a pure backend without React in its graph.

## `@kitr/server` runs standalone

The plan treated the server package as the Start add-on. It is a complete h3 server on srvx, with a `fetch` handler that Start, Nitro or any runtime can mount. `kitr new --kit server` is a first-class kit. Inside a React project `kitr add server` switches the app to TanStack Start, rewrites the root route into the HTML shell, removes `index.html` and `app/main.tsx`, and adds `kitr serve` for production.

## `@kitr/http` is its own package

The plan folded the HTTP client into the data layer. Keeping ky separate means a backend-only project, or a project talking only to its own Start actions, never installs it.

## `Form` from `kitr/forms` is kitr's

The one place a re-export is shadowed. `kitr/forms` exports kitr's `<Form>` (submits through `handleSubmit`, maps server `fieldErrors` with `applyServerErrors`, exposes `useFormStatus`), and React Hook Form's own `Form` is available as `RhfForm`. Every other name from React Hook Form is unchanged.

## Route files import `createFileRoute` from `@tanstack/react-router`

TanStack's route generator rewrites the `createFileRoute` import in every route file and only recognises `@tanstack/react-router` as its source. Routing it through `kitr/router` produced duplicate imports on build. Route files import route creators from `@tanstack/react-router` and everything else from `kitr/router`; `kitr doctor` allows exactly that set of names.

## TanStack Table v9

The plan assumed v8's `useReactTable`. v9 is feature-sliced (`useTable({ features })`), which fits "everything is an add-on": a data table only ships sorting, pagination, filtering and visibility. `kitr/table` exports `dataTableFeatures` as the preset the registry's `data-table` and `useUrlTableState` assume.

## Registry components use native `<dialog>` and no headless library

Components are copied into the app and owned there, so they should have as few runtime dependencies as possible: Tailwind, `cva` and the platform. `Dialog` is a `<dialog>` with `showModal()`; Escape and focus trapping come from the browser.

## Config and providers reach the app as static imports

Instead of a runtime glob, the Vite plugin exposes `virtual:kitr/providers` and `virtual:kitr/config`, generated from `kitrrc.ts` and `config/*.ts`. Tree-shaking sees plain imports. Server-only projects have no Vite, so `kitr add` maintains `config/index.ts` with the same shape.

## `kitr/testing` split

`renderWithKitr` pulls Testing Library and React. It moved to `kitr/testing/react`, so `kitr/testing` stays usable in a pure backend's tests.

## `app.mode` beside `app.environment`

The plan had `environment` (client/server/test) only. Providers also need to know development from production (console analytics in dev, nothing in prod; devtools on or off), so `createApp` detects `mode` from Vite's `import.meta.env` or `NODE_ENV` and exposes `isDevelopment`/`isProduction`.

## Platforms are packages, not add-ons

The first version shipped `pwa`, `electron`, `tauri` and `capacitor` as capability packages that each patched `vite.config.ts` and `package.json` scripts. They are now four platform packages (`@kitr/web`, `@kitr/server`, `@kitr/desktop`, `@kitr/mobile`) built on one contract, `definePlatform` in `@kitr/core`. A project lists where it runs in `kitrrc.ts` (`platforms: { site: web({...}), api: server({...}) }`), `kitr dev|build|start <name>` run them, `kitr config <name> <option> <value>` edits them with validation, `KITR_<NAME>_<OPTION>` overrides at run time, and native projects live in `platforms/<name>/`. Every UI platform renders through TanStack Start (SPA, static and SSR are modes of the same build), so the router is itself an add-on and a project starts with nothing but `@kitr/core` and the CLI. The vendor CLIs (`tauri`, `cap`, `electron-vite`, `wrangler`) are still what runs underneath; the platform packages only know how to call them.

The cross-platform helpers that used to be split by vendor are one package, `@kitr/platform`, with a driver registry the desktop and mobile packages fill (`platform()`, `isNative()`, `useBackButton`, `useDeepLink`, `useSafeArea`...), and `@kitr/storage` gained native drivers the same way. `analytics` and `monitoring` stay capability packages.

## Fewer packages with clearer names

`styling` and `ui` merged into `theme` (tokens, theme provider, toast, the registry settings for `kitr ui add`). `ssr` became `seo`, since Start owns server rendering and what the package adds is head tags, JSON-LD, prerender lists, sitemap and robots. `socket` and `socket.io` merged into `realtime` with `ws`, `socket.io` and `sse` transports behind one channel definition. Validation moved into `@kitr/core`.

## Devtools and storage

Also not in the plan. `@kitr/devtools` follows the provider model: the hub is a container binding that exists only in development on the client, providers contribute panels through an optional `devtools()` method on the provider interface (lazy-importing their React parts), and `getDevtools(app)` is `null` everywhere else so logging costs nothing. The overlay has no dependencies beyond React. `@kitr/storage` makes browser storage and cookies declarations (`defineStorage`, `defineCookie`) so the same module reads on the server, in `useSyncExternalStore`-based hooks, and in tests. `createKitrRouter` now binds `router` into the container so devtools (and services) can reach it.

## Packages ship their own setup

The CLI used to hold every package's setup as a recipe, so adding a package meant editing the CLI, and a community package could not be added at all. A package now exports a setup module (`<package>/kitr`, written with `definePackage` from `@kitr/core/package`) with its questions, codemods, commands, generators and doctor checks, and the CLI discovers it from the installed package. The questions are also flags, so the "no prompts in CI" rule survives. See [package-contract.md](/docs/package-contract). The official packages move onto it one by one; the recipes left in the CLI are the fallback for the rest.

## Extra commands

`kitr dev|build|start`, `kitr platforms`, `kitr config`, `kitr info`, `kitr types` (generated types under `.kitr/`, see below), `kitr css:types` (typed CSS Modules for the no-Tailwind path), and `kitr eject all` printing the import rewrites that remove kitr. `make:*` generators can be overridden per project via `kitr eject stub <kind>`.

## What is not in this version

- Prerendering and sitemap generation are configured (`config/seo.ts`) and delegate to Start's own prerender; kitr adds no crawler.
- The Socket.IO Redis adapter is wired through `attachSocketIo(io)`; the adapter itself is yours to install.
- The Next-tier packages from the package map (`secure-storage`, `files`, `notifications`, `native`, `updater`, `offline`, `flags`, `consent`, `cache`, `shield`, `mail`, `jobs`, `uploads`) are not here yet.
- Better Auth is supported through `betterAuthAdapter(client)`; no auth server is shipped.
- npm publishing is prepared (changesets, lockstep versions) but nothing is published yet.

## Queries and mutations by name

The plan had `defineAction('projects.update', { method: 'GET' })` for reads and `.query()` / `.mutation()` adapters for TanStack Query. That is gone. `kitr/actions` has `defineQuery(name, { input, handler, staleTime })` and `defineMutation(name, { input, handler, effects })`, the same two words as `kitr/query`'s contract-based pair; the import path says which one you are holding, and a server definition is also a `kitr/query` definition, so `.options(input)` and `useMutation(definition)` work on it unchanged.

The name is not decoration. `kitr types` scans `app/actions`, writes `.kitr/actions.ts` and augments `Operations` in `@kitr/core`, and `app/app.ts` passes the generated `operations` to `createApp`. `useQuery`, `useSuspenseQuery`, `useMutation` and `queryOptions` in `kitr/query` take that name as their first argument, which is a departure from TanStack's signature: `useQuery('projects.list', input, overrides)`. Plain TanStack options still pass straight through, so nothing written against upstream breaks. `call(name, input)` runs one outside React, and the generated `actions` tree gives `actions.projects.list(input)` for scripts.

Type generation is general. A package exports `defineTypes({ name, watch, generate })` from a `./types` subpath and names it in its manifest (`"kitr": { "types": "./types" }`); the CLI runs every generator the project's packages declare and writes under `.kitr/`, before `kitr dev` and `kitr build`, on change in the dev server, and on `kitr types`. The `platforms` generator is built in and types `app.platform` with the names from `kitrrc.ts`. `make:action` is replaced by `make:query` and `make:mutation`.