# Router API

Every export of kitr/router, with its signature.

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