# SEO API

Every export of kitr/seo, with its signature.

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