Routar

https://github.com/minr2kb/routar
Admin
Schema-first HTTP API client with end-to-end type safety and runtime validation, featuring...
Tokens:53,197
Snippets:613
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Complete Routar Setup

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/architecture.mdx

This example shows how to wire together all layers of a Routar API definition in a single file. It defines a router for '/todos' with getList and getDetail endpoints, creates an API client, and sets up query bindings.

```typescript
// remote/services/todo.ts
const todoRouter = defineRouter('/todos', {
  getList:   endpoint({ ... }),
  getDetail: endpoint({ ... }),
})

const todoApi   = createApi(fetchExecutor, todoRouter) // Layers 2–4 — client
export const todoQuery  = createQueries(todoApi)       // Layer 5 — query bindings
export type TodoApiTypes = ApiTypes<typeof todoApi>
```

--------------------------------

### Install dependencies

Source: https://github.com/minr2kb/routar/blob/main/packages/react-query/README.md

Installation commands for bun and npm environments.

```bash
bun add @routar/react-query @tanstack/react-query
# peer dep: @tanstack/react-query@^5  (@routar/core is a regular dependency, installed automatically)
```

```bash
npm install @routar/react-query @tanstack/react-query
```

--------------------------------

### Install @routar/msw and msw

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/mocking.mdx

Install the necessary packages for mocking with MSW and @routar/msw.

```bash
npm install @routar/msw msw
```

--------------------------------

### Install @routar/core with HTTP client

Source: https://github.com/minr2kb/routar/blob/main/README.md

Install the core package along with your preferred HTTP client adapter.

```bash
# with fetch (built into core)
npm install @routar/core

# with axios
npm install @routar/core @routar/axios axios

# with ky
npm install @routar/core @routar/ky ky
```

--------------------------------

### Request Shape Examples

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Examples showing how to define query parameters and combined path/body parameters.

```ts
// query params
endpoint({
  method: 'GET', path: '/search',
  request: { query: z.object({ q: z.string(), limit: z.number().optional() }) },
  response: z.array(TodoSchema),
});

// path + body
endpoint({
  method: 'PUT', path: '/:id',
  request: {
    path: z.object({ id: z.number() }),
    body: z.object({ title: z.string(), completed: z.boolean() }),
  },
  response: TodoSchema,
});
```

--------------------------------

### Install

Source: https://github.com/minr2kb/routar/blob/main/packages/ky/README.md

Install the necessary packages for @routar/ky.

```bash
npm install @routar/core @routar/ky ky
```

--------------------------------

### Run Development Server

Source: https://github.com/minr2kb/routar/blob/main/apps/example/README.md

Command to start the development server for the @routar/example project using bun.

```bash
bun run --filter '@routar/example' dev
```

--------------------------------

### Install

Source: https://github.com/minr2kb/routar/blob/main/packages/msw/README.md

Install the necessary packages for @routar/msw.

```bash
npm install @routar/core msw
npm install --save-dev @routar/msw
```

--------------------------------

### Install routar packages

Source: https://github.com/minr2kb/routar/blob/main/AGENTS.md

Commands to install core, executor, testing, and TanStack Query packages for routar.

```bash
# fetch (zero extra dependencies)
npm install @routar/core

# with Axios
npm install @routar/core @routar/axios axios

# for testing
npm install @routar/core msw
npm install --save-dev @routar/msw

# with TanStack Query (React)
npm install @routar/core @routar/react-query @tanstack/react-query
```

--------------------------------

### Install routar dependencies

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Installation commands for the core library and various supported HTTP clients, testing utilities, and integration packages.

```bash
# with fetch (built into core — zero extra dependencies)
npm install @routar/core

# with axios
npm install @routar/core @routar/axios axios

# with ky
npm install @routar/core @routar/ky ky

# for testing with MSW
npm install @routar/core msw
npm install --save-dev @routar/msw

# with TanStack Query (React)
npm install @routar/core @routar/react-query @tanstack/react-query
```

--------------------------------

### Basic setup with createMswHandlers

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Initializes an MSW server using handlers generated from a todoRouter. Includes lifecycle hooks for server management.

```ts
import { createMswHandlers } from '@routar/msw';
import { HttpResponse } from 'msw';
import { setupServer } from 'msw/node';
import { todoRouter } from './todo';

// Basic setup
const server = setupServer(
  ...createMswHandlers(todoRouter, 'https://api.example.com', {
    getList: () =>
      HttpResponse.json([{ id: 1, title: 'Buy milk', completed: false }]),
    getDetail: ({ params }) =>
      HttpResponse.json({ id: params.id, title: 'Buy milk', completed: false }),
    create: ({ body }) =>
      HttpResponse.json({ id: 2, title: body.title, completed: false }),
  }),
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```

--------------------------------

### Query Accessors (GET)

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Usage examples for GET endpoints using TanStack Query hooks.

```ts
useSuspenseQuery(todoQuery.getList({ query: { userId: 1 } }));
useQuery(todoQuery.getDetail({ path: { id } }, { staleTime: 60_000 }));
queryClient.prefetchQuery(todoQuery.getList()); // SSR prefetch
useSuspenseQueries({ queries: [todoQuery.getDetail({ path: { id } })] });
```

--------------------------------

### JSDoc example usage

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/ai-integration.mdx

Examples of how routar functions appear in editor hover documentation.

```ts
// Hover over endpoint( in your editor:
endpoint({
  method: 'GET',
  path: '/:id',
  request: { path: z.object({ id: z.number() }) },
  response: TodoSchema,
});

// Hover over createMswHandlers( in your editor:
const server = setupServer(
  ...createMswHandlers(todoRouter, 'https://api.example.com', {
    getList: () => HttpResponse.json([]),
    getDetail: ({ params }) => HttpResponse.json({ id: params.id }),
  }),
);
```

--------------------------------

### Setup MSW server for testing

Source: https://github.com/minr2kb/routar/blob/main/AGENTS.md

Configures an MSW server using createMswHandlers to mock API responses for a todoRouter.

```ts
import { createMswHandlers } from '@routar/msw';
import { HttpResponse } from 'msw';
import { setupServer } from 'msw/node';

const server = setupServer(
  ...createMswHandlers(todoRouter, 'https://api.example.com', {
    getList: () =>
      HttpResponse.json([{ id: 1, title: 'Buy milk', completed: false }]),
    getDetail: ({ params }) =>
      HttpResponse.json({ id: params.id, title: 'Buy milk', completed: false }),
    create: ({ body }) =>
      HttpResponse.json({ id: 2, title: body.title, completed: false }),
  }),
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```

--------------------------------

### Define a Basic Router

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/define-router.mdx

This snippet shows how to define a router for 'todos' endpoints with a '/todos' prefix. It includes examples for GET and POST methods with request and response schemas.

```typescript
import { defineRouter, endpoint } from '@routar/core'

const todoRouter = defineRouter('/todos', {
  getList:   endpoint({ method: 'GET',  path: '/',    response: TodoListSchema }),
  getDetail: endpoint({ method: 'GET',  path: '/:id', response: TodoSchema,
                        request: { path: z.object({ id: z.number() }) } }),
  create:    endpoint({ method: 'POST', path: '/',    response: TodoSchema,
                        request: { body: z.object({ title: z.string() }) } }),
})
```

--------------------------------

### Install Routar React Query dependencies

Source: https://github.com/minr2kb/routar/blob/main/README.md

Install the necessary packages to enable TanStack Query integration with Routar.

```bash
npm install @routar/react-query @tanstack/react-query
```

--------------------------------

### Install Routar Axios Dependencies

Source: https://github.com/minr2kb/routar/blob/main/packages/axios/README.md

Install the necessary packages for @routar/axios, including the core Routar library and Axios itself.

```bash
npm install @routar/core @routar/axios axios
```

--------------------------------

### Create Fetch Executor

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/executors/fetch.mdx

Initialize the fetch executor with a base URL. This is the basic setup for using the executor.

```typescript
import { createFetchExecutor } from '@routar/core'

const executor = createFetchExecutor('https://api.example.com')
```

--------------------------------

### Parsing requests with path and body

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/create-parser.mdx

Example of assembling a request envelope containing both path parameters and a body.

```ts
const update = createParser(TodoRouter.endpoints.update)
const { path, body } = await update.parseRequest({
  path: { id: params.id },      // string → coerced by the spec's path schema
  body: await req.json(),
})
```

--------------------------------

### Nested Routers Example

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/define-router.mdx

Demonstrates how to create nested routers to mirror URL structure in the type system, allowing for complex API hierarchies.

```APIDOC
## Nested Routers

Mirror your URL structure in the type system by nesting `defineRouter` calls.

### Example
```ts
const apiRouter = defineRouter('/api', {
  users: defineRouter('/users', {
    getList:   endpoint({ method: 'GET', path: '/',    response: UserListSchema }),
    getDetail: endpoint({ method: 'GET', path: '/:id', response: UserSchema }),

    todos: defineRouter('/todos', {
      getList: endpoint({ method: 'GET', path: '/', response: TodoListSchema }),
    }),
  }),
})

const api = createApi(executor, apiRouter)

await api.users.getList({})                         // GET /api/users
await api.users.getDetail({ path: { id: 1 } })      // GET /api/users/1
await api.users.todos.getList({})                   // GET /api/users/todos
```
```

--------------------------------

### Inline Usage Example

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/define-router.mdx

Shows how to use endpoints directly with `createApi` without explicitly defining a router using `defineRouter`, either with or without a prefix.

```APIDOC
## Inline Usage

You can skip `defineRouter` and pass endpoints directly to `createApi`:

### Example
```ts
// pre-built router (prefix comes from defineRouter)
const api = createApi(executor, todoRouter)

// inline with explicit prefix
const api = createApi(executor, '/todos', { getList: endpoint({ ... }) })

// inline without prefix (flat endpoint map)
const api = createApi(executor, { getList: endpoint({ ... }) })
```

Use `defineRouter` when you want to reuse the router definition across multiple executors (SSR/CSR pattern).
```

--------------------------------

### definePlugin interface and examples

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Defines the ExecutorPlugin interface and provides examples for correlation ID and auth plugins.

```ts
interface ExecutorPlugin {
  name?: string;
  onRequest?: (opts: ExecuteOptions) => ExecuteOptions | Promise<ExecuteOptions>;
  onResponse?: (response: unknown, opts: ExecuteOptions) => unknown | Promise<unknown>;
  onError?: (error: unknown, opts: ExecuteOptions) => never | Promise<never>;
}

// Add a correlation ID header to every request
const correlationPlugin = definePlugin({
  name: 'correlation-id',
  onRequest: (opts) => ({
    ...opts,
    headers: { ...opts.headers, 'X-Request-Id': crypto.randomUUID() },
  }),
});

// Bundle auth header injection + 401 refresh into a single plugin
const authPlugin = definePlugin({
  name: 'auth',
  onRequest: async (opts) => ({
    ...opts,
    headers: { ...opts.headers, Authorization: `Bearer ${await getToken()}` },
  }),
  onError: async (err) => {
    if (err instanceof HttpError && err.status === 401) await refreshToken();
    throw err; // onError must re-throw
  },
});
```

--------------------------------

### Using createParser in server handlers

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Examples of using createParser with Next.js Route Handlers and Hono/Express, demonstrating request and response validation.

```ts
import { createParser } from '@routar/core';
import { TodoRouter } from '@/remote/services/todo';

const listParser = createParser(TodoRouter.endpoints.getList);
const createParserFor = createParser(TodoRouter.endpoints.create);

// Next.js Route Handler — assemble the { path, query, body } envelope yourself
export async function POST(req: NextRequest) {
  try {
    const { body } = await createParserFor.parseRequest({ body: await req.json() });
    return Response.json(createTodo(body), { status: 201 });
  } catch (err) {
    if (err instanceof ZodError) return Response.json({ error: err.flatten() }, { status: 400 });
    throw err;
  }
}

// path params: the spec's request.path schema coerces the raw string id — no manual Number(id)
const updateParser = createParser(TodoRouter.endpoints.update);
const { path, body } = await updateParser.parseRequest({ path: { id }, body: await req.json() });

// same parser, different glue — Hono / Express work identically
app.post('/todos', async (c) => {
  const { body } = await createParserFor.parseRequest({ body: await c.req.json() });
  return c.json(createTodo(body), 201);
});

// validate the response too — confirm the server produced contract-shaped data (adapter NOT applied)
const detailParser = createParser(TodoRouter.endpoints.getDetail);
return ok(await detailParser.parseResponse(rowFromDb));
```

--------------------------------

### Example Application Directory Structure

Source: https://github.com/minr2kb/routar/blob/main/CLAUDE.md

The standard directory layout for a Routar-based application, highlighting API route handlers, server components, and client-side service definitions.

```text
app/
  api/todos/        local Route Handlers (GET/POST + GET/PATCH/DELETE /:id)
  api/todos/_store.ts  in-memory store seeded via globalThis (survives hot-reload)
  (pages)/          server components: prefetchQuery → HydrationBoundary → <Suspense>
  providers.tsx     QueryClientProvider with useState (never pass QueryClient across boundary)
  layout.tsx        root layout wrapping with Providers
utils/
  get-query-client.ts  isServer-based singleton — fresh per request on server, stable on client
remote/
  lib/executor.ts   clientExecutor (axios+interceptors, CSR) + fetchExecutor (fetch+cookies, SSR)
                    localClientExecutor + localFetchExecutor (→ NEXT_PUBLIC_APP_URL)
  services/
    <domain>.ts          one file per domain: defineRouter + endpoint() + createApi
                         + createQueries (TanStack Query helpers) + ApiTypes export
components/
  *Client.tsx       client components using useSuspenseQuery / useSuspenseQueries
```

--------------------------------

### Install Routar Core Package

Source: https://github.com/minr2kb/routar/blob/main/packages/core/README.md

Install the @routar/core package using npm. This command adds the core library to your project dependencies.

```bash
npm install @routar/core
```

--------------------------------

### QueryClient Configuration

Source: https://github.com/minr2kb/routar/blob/main/packages/react-query/README.md

Required setup to enable the `invalidates` feature using `routarMutationCache`.

```APIDOC
## QueryClient Configuration

### Description
To enable declarative invalidation, you must wire the `routarMutationCache` into your TanStack `QueryClient` instance.

### Usage
```ts
import { QueryClient } from "@tanstack/react-query";
import { routarMutationCache } from "@routar/react-query";

const queryClient = new QueryClient({
  mutationCache: routarMutationCache(() => queryClient),
});
```
```

--------------------------------

### Create Typed API Client

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/create-api.mdx

Import `createApi` and use it with an executor and router to get a typed API client. Call endpoints with parameters structured as { path?, query?, body? }.

```typescript
import { createApi } from '@routar/core'

const todoApi = createApi(executor, todoRouter)

// params follow { path?, query?, body? }
await todoApi.getDetail({ path: { id: 1 } })
await todoApi.create({ body: { title: 'buy milk' } })
await todoApi.update({ path: { id: 1 }, body: { completed: true }, query: { version: 2 } })
```

--------------------------------

### Setup MSW Worker for Browser

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/mocking.mdx

Configure and export the MSW worker for browser environments, combining all defined handlers.

```typescript
// mocks/browser.ts
import { setupWorker } from 'msw/browser'
import { allHandlers } from './handlers'

export const worker = setupWorker(...allHandlers)
```

--------------------------------

### Typed Resolver Context Example

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/mocking.mdx

Demonstrates how each resolver receives a typed context derived from the endpoint's request schema, including params, query, body, request, and cookies.

```typescript
createMswHandlers(TodoRouter, BASE_URL, {
  // params.id is number when path schema uses z.coerce.number()
  getDetail: ({ params, query, body, request, cookies }) =>
    HttpResponse.json({ id: params.id, title: 'Typed!' }),
})
```

--------------------------------

### Plugin Execution Order Example

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/plugins.mdx

Illustrates the order in which plugins are executed during a request. The first plugin in the declaration order acts as the outermost wrapper.

```typescript
createExecutor(transport, { plugins: [authPlugin, logger()] })
// onRequest:  authPlugin → logger → transport
// onResponse: logger → authPlugin
// onError:    logger → authPlugin
```

--------------------------------

### Basic TypeScript Fetch Wrapper

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/why.mdx

A common starting point for API layers using TypeScript and fetch. Be aware that runtime data may not match compile-time types.

```typescript
async function getTodo(id: number): Promise<Todo> {
  const res = await fetch(`/todos/${id}`)
  return res.json() as Todo
}
```

--------------------------------

### Custom Executor with Dynamic Authorization Header

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/custom-executor.mdx

Implement dynamic authorization headers for per-request authentication. This example shows how to fetch a token and include it in the Authorization header.

```typescript
import { createExecutor, serializeParams } from '@routar/core'

const executor = createExecutor(async ({ method, url, params, body, headers, signal }) => {
  const token = await getAccessToken()

  const fullURL = new URL(url)
  if (params) {
    serializeParams(params).forEach((v, k) => fullURL.searchParams.set(k, v))
  }

  const res = await fetch(fullURL.toString(), {
    method,
    body: body != null ? JSON.stringify(body) : undefined,
    headers: {
      ...(body != null ? { 'Content-Type': 'application/json' } : {}),
      Authorization: `Bearer ${token}`,
      ...headers,
    },
    signal,
  })
  if (!res.ok) throw new Error(`HTTP ${res.status}`)
  return res.json()
})
```

--------------------------------

### defineRouter() Usage

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/define-router.mdx

Defines a router with a base path and a collection of endpoints or nested routers. This example shows how to define a router for 'todos' with GET, POST, and nested routes.

```APIDOC
## defineRouter(prefix, endpoints)

### Description
Groups endpoints under a shared URL prefix. Supports arbitrary nesting.

### Parameters

#### Path Parameters
* **prefix** (string) - Required - URL prefix for all endpoints in this router
* **endpoints** (Record<string, endpoint | defineRouter>) - Required - Named endpoints or nested routers

### Example
```ts
import { defineRouter, endpoint } from '@routar/core'

const todoRouter = defineRouter('/todos', {
  getList:   endpoint({ method: 'GET',  path: '/',    response: TodoListSchema }),
  getDetail: endpoint({ method: 'GET',  path: '/:id', response: TodoSchema,
                        request: { path: z.object({ id: z.number() }) } }),
  create:    endpoint({ method: 'POST', path: '/',    response: TodoSchema,
                        request: { body: z.object({ title: z.string() }) } }),
})
```
```

--------------------------------

### createQueries(api, options?)

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/create-queries.mdx

Derives typed queryOptions and mutationOptions factories from a routar API client. The returned object mirrors the router's shape, where GET endpoints become query accessors and non-GET endpoints become mutation accessors.

```APIDOC
## createQueries(api, options?)

### Description
Derives typed `queryOptions` and `mutationOptions` factories from a routar API client. The returned object mirrors the router's shape, where GET endpoints become query accessors and non-GET endpoints become mutation accessors.

### Parameters
- **api** (ApiClientWithRouter) - Required - The typed client produced by `createApi`.
- **options.key** (string | string[]) - Optional - Override the root key segments.
- **options.defaults** (Record<string, Options | ((params, q) => Options)>) - Optional - Per-endpoint default options keyed by endpoint name.
- **options.infinite** (Record<string, { initialPageParam, getNextPageParam, pageParam }>) - Optional - Per-endpoint infinite query contract keyed by GET endpoint name.
- **options.flatten** (boolean) - Optional - When `true`, accessors accept flat params instead of the nested envelope. Default: `false`.
- **options.queryEndpoints** (Record<string, true | nested>) - Optional - Promote non-GET endpoints to query accessors.

### Usage Example
```ts
import { createQueries } from '@routar/react-query'
import { todoApi } from './todo'

export const todoQuery = createQueries(todoApi, {
  defaults: {
    getDetail: { staleTime: 5 * 60_000 },
    getList: (params, _q) => ({ staleTime: params?.query?.done ? 60_000 : 0 }),
    create: (_, q) => ({ invalidates: [q.getList.queryKey()] }),
  },
})
```
```

--------------------------------

### Initialize QueryClient with routarQueryClient

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/create-queries.mdx

Compares manual QueryClient configuration with the simplified factory approach.

```ts
import { routarQueryClient } from '@routar/react-query'

// Before — manual self-reference:
let queryClient: QueryClient
queryClient = new QueryClient({
  mutationCache: routarMutationCache(() => queryClient),
})

// After:
const queryClient = routarQueryClient()
```

--------------------------------

### Initialize and use createParser

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/create-parser.mdx

Demonstrates creating a parser from an endpoint and using it to validate a request body.

```ts
import { createParser } from '@routar/core'
import { TodoRouter } from '@/remote/services/todo'

const createParserFor = createParser(TodoRouter.endpoints.create)

// server framework glue — assemble the { path, query, body } envelope yourself
const { body } = await createParserFor.parseRequest({ body: await req.json() })
//      ^? { title: string; completed: boolean; userId: number }  (validated)
```

--------------------------------

### Initialize createFetchExecutor with various configurations

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Demonstrates initializing the executor with static or dynamic base URLs, and configuring default headers for SSR or Next.js environments.

```ts
import { createFetchExecutor } from '@routar/core';

// Minimal
const executor = createFetchExecutor('https://api.example.com');

// Dynamic base URL — absolute on the server, relative on the client
const executor = createFetchExecutor(
  () => (typeof window === 'undefined' ? 'http://localhost:3000/api' : '/api'),
);

// With SSR dynamic headers
const executor = createFetchExecutor('https://api.example.com', {
  defaultHeaders: async () => {
    const token = await getServerToken();
    return token ? { Authorization: `Bearer ${token}` } : {};
  },
});

// Next.js App Router — forward cookies from the incoming request
const executor = createFetchExecutor('https://api.example.com', {
  defaultHeaders: async () => {
    const { cookies } = await import('next/headers');
    const token = (await cookies()).get('access_token')?.value;
    return token ? { Authorization: `Bearer ${token}` } : {};
  },
  retry: 2,
  timeout: 8_000,
});
```

--------------------------------

### API Client Usage

Source: https://github.com/minr2kb/routar/blob/main/README.md

Demonstrates how to initialize the API client using a fetch executor and invoke defined endpoints directly with optional AbortSignal support.

```APIDOC
## API Client Usage

### Description
Initialize the API client and invoke endpoints as typed async functions. Supports request cancellation via AbortSignal.

### Usage
```ts
const todoApi = createApi(createFetchExecutor('https://api.example.com'), todoRouter);

// Call directly
const todos = await todoApi.getList({});

// Call with AbortSignal
const controller = new AbortController();
const todo = await todoApi.getDetail({ path: { id: 1 } }, controller.signal);
controller.abort();
```
```

--------------------------------

### Configure QueryClient with default options

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/create-queries.mdx

Demonstrates passing standard QueryClientConfig options to the factory.

```ts
const queryClient = routarQueryClient({
  defaultOptions: { queries: { staleTime: 60_000 } },
})
```

--------------------------------

### Usage

Source: https://github.com/minr2kb/routar/blob/main/packages/msw/README.md

Example of how to use createMswHandlers to generate mock handlers for a routar router.

```typescript
import { createMswHandlers } from '@routar/msw'
import { HttpResponse } from 'msw'
import { setupServer } from 'msw/node'
import { todoRouter } from './api'

const server = setupServer(
  ...createMswHandlers(todoRouter, 'https://api.example.com', {
    getList: () => HttpResponse.json([{ id: 1, title: 'Todo' }]),
    getDetail: ({ params }) =>
      HttpResponse.json({ id: params.id, title: 'Todo' }),
  }),
)

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())
```

--------------------------------

### Wiring Routar Mutation Cache

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/react-query.mdx

Required setup for the QueryClient to process the invalidates property.

```ts
// utils/get-query-client.ts
import { QueryClient } from '@tanstack/react-query'
import { routarMutationCache } from '@routar/react-query'

let queryClient: QueryClient
queryClient = new QueryClient({
  mutationCache: routarMutationCache(() => queryClient),
})
```

--------------------------------

### Recommended Project Structure

Source: https://github.com/minr2kb/routar/blob/main/AGENTS.md

A directory layout for organizing API services and executors to maintain a single source of truth.

```text
remote/
  lib/
    executor.ts        # executor(s), one per environment — see Executor Selection above
  services/
    todo.ts             # one file per domain: defineRouter + endpoint()s + createApi (+ createQueries)
    user.ts
```

--------------------------------

### Mutation Accessors (non-GET)

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Usage examples for non-GET endpoints using TanStack Query mutations.

```ts
const create = useMutation(todoQuery.create());
create.mutate({ body: { title: 'buy milk' } });
```

--------------------------------

### Framework-agnostic Request Parsing

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/server-side-validation.mdx

Examples of using Routar parsers within Hono and Express frameworks.

```ts
// Hono
import { Hono } from 'hono'
const app = new Hono()

app.post('/todos', async (c) => {
  const { body } = await createParserFor.parseRequest({ body: await c.req.json() })
  return c.json(createTodo(body), 201)
})
```

```ts
// Express
app.post('/todos', async (req, res) => {
  try {
    const { body } = await createParserFor.parseRequest({ body: req.body })
    res.status(201).json(createTodo(body))
  } catch (err) {
    if (err instanceof ZodError) return res.status(400).json({ error: err.flatten() })
    throw err
  }
})
```

--------------------------------

### Initialize routarQueryClient

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Returns a QueryClient with routarMutationCache pre-configured.

```ts
import { routarQueryClient } from '@routar/react-query';
const queryClient = routarQueryClient({ defaultOptions: { queries: { staleTime: 60_000 } } });
```

--------------------------------

### SSR Prefetching with TanStack Query

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/ssr-csr.mdx

Demonstrates how to prefetch data on the server using `queryClient.prefetchQuery` with `todoListQueryOptions`. The `dispatchExecutor` automatically handles the correct fetch transport on the server.

```tsx
import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
import { getQueryClient } from '@/utils/get-query-client'
import { todoListQueryOptions } from '@/remote/services/todo'
import { Suspense } from 'react'

export default async function TodosPage() {
  const queryClient = getQueryClient()
  await queryClient.prefetchQuery(todoListQueryOptions())

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <Suspense fallback={<p>Loading…</p>}>
        <TodoListClient />
      </Suspense>
    </HydrationBoundary>
  )
}
```

--------------------------------

### Custom plugin definition

Source: https://github.com/minr2kb/routar/blob/main/README.md

Example of a custom plugin that adds a correlation ID header to every request.

```ts
const correlationPlugin = definePlugin({
  onRequest: (opts) => ({
    ...opts,
    headers: { ...opts.headers, 'X-Request-Id': crypto.randomUUID() },
  }),
});
```

--------------------------------

### Initialize createQueries

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/create-queries.mdx

Create a query factory by passing the typed API client produced by createApi.

```ts
import { createQueries } from '@routar/react-query'
import { todoApi } from './todo'

export const todoQuery = createQueries(todoApi)
```

--------------------------------

### Endpoint with Adapter

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/endpoint.mdx

Defines a GET endpoint with an adapter to transform the raw response data into a different shape.

```APIDOC
## GET /

### Description
Defines a GET endpoint that returns an array of Todo items and transforms them using an adapter to add a 'label' field.

### Method
GET

### Endpoint
/

### Parameters
#### Request Body
None

#### Query Parameters
None

#### Path Parameters
None

### Response
#### Success Response (200)
- **id** (number) - Description of the id field
- **title** (string) - Description of the title field
- **label** (string) - The transformed label field
```

--------------------------------

### createApi() Usage

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/create-api.mdx

Demonstrates how to use `createApi` to create a typed API client. The generated client's methods accept parameters structured as `{ path?, query?, body? }` and return Promises.

```APIDOC
## `createApi(executor, router)`

Produces a fully-typed API client. Each endpoint becomes an async function with the signature `(params, signalOrOptions?) => Promise<Response>` — the second argument is an `AbortSignal` or a `{ signal?, headers?, timeout? }` options object.

```ts
import { createApi } from '@routar/core'

const todoApi = createApi(executor, todoRouter)

// params follow { path?, query?, body? }
await todoApi.getDetail({ path: { id: 1 } })
await todoApi.create({ body: { title: 'buy milk' } })
await todoApi.update({ path: { id: 1 }, body: { completed: true }, query: { version: 2 } })
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `executor` | `Executor` | HTTP transport. Create with `createFetchExecutor` or `createAxiosExecutor`. |
| `router` | `RouterDef \| RouterEndpoints` | Router definition or inline endpoints record |
| `prefix` | `string` (optional) | URL prefix when passing endpoints inline |

### Request params

Request params map to `{ path?, query?, body? }` matching the `request` schema shape:

```ts
// request: { path: z.object({ id: z.number() }) }
await api.getDetail({ path: { id: 1 } })

// request: { query: z.object({ page: z.number() }) }
await api.getList({ query: { page: 2 } })

// request: { body: z.object({ title: z.string() }) }
await api.create({ body: { title: 'buy milk' } })
```

### Per-call options

The second argument accepts either a bare `AbortSignal` (backward compatible) or an options object `{ signal?, headers?, timeout? }`:

```ts
// cancel with an AbortSignal
const controller = new AbortController()
await todoApi.getList({}, controller.signal)
controller.abort()

// per-call headers + timeout
await todoApi.create(
  { body: { title: 'buy milk' } },
  {
    headers: { 'Idempotency-Key': key }, // merged over executor defaults
    timeout: 30_000,                      // throws TimeoutError when exceeded
    signal: controller.signal,
  },
)
```

- **`headers`** are seeded onto the request and merged over the executor's default headers (per-call wins). A plugin's `onRequest` runs afterward and wins on a key collision (plugins are cross-cutting policy such as auth).
- **`timeout`** aborts the request with a `TimeoutError` and is applied by the core client, so it works on every executor (fetch, Axios, ky, custom) and composes with any executor-level timeout (whichever fires first).

### Validation modes

`validate` controls whether request/response schemas run, per phase. Each phase accepts `true` (default — validate and throw on failure), `false` (skip), or `'warn'`:

```ts
// observe response drift without breaking production
const api = createApi(executor, todoRouter, {
  validate: { request: true, response: 'warn' },
  onValidationError: (err, ctx) => {
    // ctx: { kind: 'request' | 'response', method, url, data }
    Sentry.captureException(err, { extra: ctx })
  },
})
```

In `'warn'` mode a parse failure passes the **raw** data through (no outage) and calls `onValidationError(error, context)` instead of throwing — the drift-observation middle ground between full validation and `validate: false`. `onValidationError` is never called under `true` (which throws) or `false` (which skips).

### SSR/CSR pattern

The typical pattern is to create two clients from the same router — one for CSR, one for SSR:

```ts
export const todoApi       = createApi(clientExecutor, todoRouter) // CSR
export const todoServerApi = createApi(serverExecutor, todoRouter) // SSR
```

See the [SSR/CSR guide](/en/guides/ssr-csr) for a complete example.
```

--------------------------------

### Basic Endpoint Definition

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/endpoint.mdx

Defines a simple GET endpoint without an adapter, specifying the response schema.

```APIDOC
## GET /

### Description
Defines a simple GET endpoint that returns an array of Todo items.

### Method
GET

### Endpoint
/

### Parameters
#### Request Body
None

#### Query Parameters
None

#### Path Parameters
None

### Response
#### Success Response (200)
- **id** (number) - Description of the id field
- **title** (string) - Description of the title field
```

--------------------------------

### logger usage

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Demonstrates default and custom logger configurations.

```ts
logger()  // defaults to console.log
logger({ log: (msg, data) => myLogger.debug(msg, data) })
```

--------------------------------

### createApi()

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/index.mdx

Builds a typed API client by combining an executor and a router configuration.

```APIDOC
## createApi()

### Description
Builds a typed API client by combining an executor and a router configuration.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Branch Dispatch Executor by URL Prefix

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/dispatch-executor.mdx

Chooses an executor based on whether the request URL starts with '/internal'.

```typescript
// Branch by URL prefix
dispatchExecutor((opts) =>
  opts.url.startsWith('/internal') ? internalExecutor : publicExecutor
)
```

--------------------------------

### Plugin configuration

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Shows how to apply plugins to an executor using the options object.

```ts
import { createExecutor, definePlugin, logger } from '@routar/core';
import { HttpError } from '@routar/core';

const executor = createExecutor(transport, {
  plugins: [authPlugin, logger()],
});
```

--------------------------------

### Vanilla Usage of routar

Source: https://github.com/minr2kb/routar/blob/main/README.md

Demonstrates creating an API client with a fetch executor and calling endpoints directly. Shows how to use AbortController to cancel in-flight requests.

```ts
const todoApi = createApi(createFetchExecutor('https://api.example.com'), todoRouter);

// call directly
const todos = await todoApi.getList({});
renderTodoList(todos); // todos is typed as Todo[]

// cancel in-flight requests with AbortSignal
const controller = new AbortController();
const todo = await todoApi.getDetail({ path: { id: 1 } }, controller.signal);
controller.abort();
```

--------------------------------

### Validator Compatibility Example

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/custom-executor.mdx

Illustrates how to use a hand-rolled validator with a '.parse(data: unknown): T' method for endpoint response validation in Routar.

```typescript
// hand-rolled validator
const TodoValidator = {
  parse(data: unknown): Todo {
    if (typeof data !== 'object' || data === null) throw new Error('invalid')
    return data as Todo
  },
}

endpoint({ method: 'GET', path: '/', response: TodoValidator })
```

--------------------------------

### Usage of API client

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms-full.txt

Demonstrates basic calls, nested router access, request cancellation with AbortSignal, per-call options, validation modes, and type extraction.

```ts
// basic calls
const todos = await todoApi.getList({});
const todo  = await todoApi.getDetail({ path: { id: 1 } });
const next  = await todoApi.create({ body: { title: 'buy milk' } });

// nested router access via dot notation
const api = createApi(executor, apiRouter);
await api.todos.getList({});
await api.users.getDetail({ path: { id: 1 } });
await api.users.todos.getList({});  // deeply nested

// cancel in-flight requests with AbortSignal
const controller = new AbortController();
const todos = await todoApi.getList({}, controller.signal);
controller.abort();

// per-call options: headers + timeout (transport-agnostic)
await todoApi.create({ body: { title: 'x' } }, {
  headers: { 'Idempotency-Key': key }, // merged over executor defaults (plugin onRequest wins on collision)
  timeout: 30_000,                      // aborts with TimeoutError; composes with executor timeout
  signal: controller.signal,
});

// skip response validation in production
const prodApi = createApi(executor, todoRouter, {
  validate: { request: true, response: process.env.NODE_ENV !== 'production' },
});

// validate modes: true (default, throws) | false (skip) | 'warn' (observe drift)
// 'warn' passes raw data through and calls onValidationError instead of throwing
const driftApi = createApi(executor, todoRouter, {
  validate: { request: true, response: 'warn' },
  onValidationError: (err, ctx) => report(ctx), // ctx: { kind: 'request'|'response', method, url, data }
});

// extract types from the client — no duplication
import type { ApiTypes } from '@routar/core';
type TodoApiTypes    = ApiTypes<typeof todoApi>;
type Todo            = TodoApiTypes['getDetail']['response']; // { id: number; title: string; completed: boolean }
type CreateRequest   = TodoApiTypes['create']['request'];     // { body: { title: string } }
```

--------------------------------

### Extracting API Types with ApiTypes

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/endpoint.mdx

Example of using the `ApiTypes` utility to extract request and response types from an API client definition.

```typescript
import type { ApiTypes } from '@routar/core'

type TodoApiTypes = ApiTypes<typeof todoApi>
type CreateRequest  = TodoApiTypes['create']['request']  // { body: { title: string } }
type CreateResponse = TodoApiTypes['create']['response'] // Todo
```

--------------------------------

### createApi Overloads for Router Definition

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/create-api.mdx

Demonstrates the different ways to define a router when using `createApi`: with a pre-built router, inline endpoints with a prefix, or inline endpoints without a prefix.

```typescript
// with a pre-built router
createApi(executor, todoRouter)

// inline with prefix
createApi(executor, '/todos', { getList: endpoint({ ... }) })

// inline without prefix
createApi(executor, { getList: endpoint({ ... }) })
```

--------------------------------

### Query Accessors

Source: https://github.com/minr2kb/routar/blob/main/packages/react-query/README.md

Every GET endpoint in your Routar client becomes a query accessor function that returns a TanStack queryOptions object.

```APIDOC
## Query Accessors

### Description
Generates a TanStack `queryOptions` object from a Routar GET endpoint. The accessor accepts optional request parameters and standard TanStack query options.

### Usage
`client.endpoint(params?, options?)`

### Parameters
- **params** (object) - Optional - The routar request object containing `path`, `query`, or `body` fields.
- **options** (object) - Optional - Any standard TanStack `useQuery` options, excluding `queryKey` and `queryFn`.

### Example
```ts
// Basic usage
const { data } = useSuspenseQuery(todoQuery.getList());

// With parameters and options
todoQuery.getList({ query: { done: true } }, { staleTime: 60_000 });
```
```

--------------------------------

### Create executor and API client

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/getting-started.mdx

Initialize the API client by creating an executor and passing it to createApi.

```ts
import { createApi } from '@routar/core'
import { createFetchExecutor } from '@routar/core'

const executor = createFetchExecutor('https://api.example.com')
const todoApi  = createApi(executor, todoRouter)
```

--------------------------------

### routarQueryClient

Source: https://github.com/minr2kb/routar/blob/main/AGENTS.md

Initializes a QueryClient with the routarMutationCache pre-wired, reducing boilerplate.

```APIDOC
## routarQueryClient(config?)

### Description
Returns a QueryClient with routarMutationCache self-wired. This replaces manual QueryClient configuration for mutation caching.

### Parameters
- **config** (QueryClientConfig) - Optional - Configuration object forwarded to the underlying QueryClient.
```

--------------------------------

### Start MSW Worker in Development

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/guides/mocking.mdx

Activate the MSW worker in the browser during development to intercept requests. Configure it to bypass unhandled requests.

```typescript
// Activate in development (e.g. providers.tsx)
if (process.env.NODE_ENV === 'development') {
  const { worker } = await import('@/remote/mocks/browser')
  await worker.start({ onUnhandledRequest: 'bypass' })
}
```

--------------------------------

### Extracting Path Parameters with PathParams

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/endpoint.mdx

Example of using the `PathParams` utility to extract named path parameters from a path string as a union type.

```typescript
import type { PathParams } from '@routar/core'

type P = PathParams<'/:userId/posts/:postId'> // 'userId' | 'postId'
```

--------------------------------

### Response Unwrap Plugin

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/plugins.mdx

An example plugin that transforms responses by unwrapping a common API envelope structure. This is useful for APIs that consistently wrap data.

```typescript
// If your API wraps responses as { data: ..., meta: ... }
const unwrapPlugin = definePlugin({
  onResponse: (res) => (res as { data: unknown }).data ?? res,
})
```

--------------------------------

### Endpoint with Request Buckets

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/endpoint.mdx

Demonstrates defining an endpoint with path and query parameters, specifying their schemas.

```APIDOC
## GET /:id

### Description
Defines a GET endpoint that accepts an ID in the path and a query parameter 'q', returning a single Todo item.

### Method
GET

### Endpoint
/:id

### Parameters
#### Path Parameters
- **id** (number) - Required - The ID of the todo item.

#### Query Parameters
- **q** (string) - Required - A query string parameter.

#### Request Body
None

### Response
#### Success Response (200)
- **id** (number) - Description of the id field
- **title** (string) - Description of the title field
```

--------------------------------

### Create fetch executor with options

Source: https://github.com/minr2kb/routar/blob/main/README.md

Configures a fetch executor with default headers, retry attempts, and timeout settings.

```ts
import { createFetchExecutor } from '@routar/core';

const executor = createFetchExecutor('https://api.example.com', {
  defaultHeaders: async () => {
    const token = await getServerToken();
    return token ? { Authorization: `Bearer ${token}` } : {};
  },
  retry: 2,
  timeout: 5000,
});
```

--------------------------------

### Correct Path Parameter Enforcement

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/endpoint.mdx

Example of correct path parameter enforcement where the `request.path` schema matches the `:param` segments in the endpoint's `path`.

```typescript
// ✅ correct
endpoint({
  path: '/:id',
  request: { path: z.object({ id: z.number() }) },
  response: TodoSchema,
  method: 'GET',
})
```

--------------------------------

### createFetchExecutor(baseURL, options?)

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/public/llms.txt

Creates a native fetch executor, suitable for SSR with dynamic headers.

```APIDOC
## createFetchExecutor(baseURL, options?)

### Description
Creates a native fetch executor. Ideal for SSR with per-request dynamic headers.

### Parameters
- **baseURL** (string | function) - Required - A static string or a sync/async factory called per request.
- **options** (object) - Optional - Configuration options including `retry` (number) and `timeout` (number).
```

--------------------------------

### Inline Router Usage with createApi

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/define-router.mdx

Shows different ways to use routers with `createApi`. This includes using a pre-built router, an inline router with an explicit prefix, and a flat endpoint map without a prefix.

```typescript
// pre-built router (prefix comes from defineRouter)
const api = createApi(executor, todoRouter)

// inline with explicit prefix
const api = createApi(executor, '/todos', { getList: endpoint({ ... }) })

// inline without prefix (flat endpoint map)
const api = createApi(executor, { getList: endpoint({ ... }) })
```

--------------------------------

### Define Endpoint With Adapter

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/endpoint.mdx

Define a GET endpoint with an adapter to transform the validated response data. The `raw` type within the adapter is inferred from the `response` schema.

```typescript
import { endpoint } from '@routar/core'
import { z } from 'zod'

const TodoSchema = z.object({ id: z.number(), title: z.string() })

// with adapter — raw is inferred as z.infer<typeof TodoSchema>[]
endpoint({
  method: 'GET',
  path: '/',
  response: z.array(TodoSchema),
  adapter: (raw) => raw.map(todo => ({ ...todo, label: todo.title })),
})
```

--------------------------------

### Configure executor with plugins

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/getting-started.mdx

Add plugins, retry logic, and timeouts to the fetch executor.

```ts
import { createFetchExecutor, logger } from '@routar/core'

const executor = createFetchExecutor('https://api.example.com', {
  plugins: [logger()],
  retry: 3,
  timeout: 8_000,
})
```

--------------------------------

### Define Endpoint Without Adapter

Source: https://github.com/minr2kb/routar/blob/main/apps/docs/content/en/api-reference/endpoint.mdx

Define a basic GET endpoint with a response schema. The `response` schema is used for validating the API's response data.

```typescript
import { endpoint } from '@routar/core'
import { z } from 'zod'

const TodoSchema = z.object({ id: z.number(), title: z.string() })

// without adapter
endpoint({
  method: 'GET',
  path: '/',
  response: z.array(TodoSchema),
})
```
Tokens:
Raw