> ## Documentation Index
> Fetch the complete documentation index at: https://docs.katla.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Static cookies

> Pre-fetch cookie data at build time to eliminate runtime network requests.

Instead of fetching cookie data at runtime, you can pre-fetch it during your build step and pass it as static data. This eliminates the client-side network request entirely.

## Configuration file

Create a `katla.config.mjs` (ESM) or `katla.config.js` (CJS) in your project root to set defaults for `katla pull`:

```js theme={null}
// katla.config.mjs
export default {
  siteId: 'your-site-id',
  dir: '.katla',
  // locale: 'en-GB',
  // format: 'full',
};
```

```js theme={null}
// katla.config.js (CommonJS)
module.exports = {
  siteId: 'your-site-id',
};
```

CLI flags always override config file values.

## CLI

With a config file, `katla pull` works without arguments:

```bash theme={null}
katla pull
```

Or pass the site ID directly:

```bash theme={null}
katla pull <site-id>
```

This fetches your site's cookie data (per-locale), policies for all locales, and the guard script, then saves them to the `.katla/` directory. Add it to your build pipeline:

```json theme={null}
{
  "scripts": {
    "prebuild": "katla pull",
    "build": "vite build"
  }
}
```

Then import the JSON and pass it to your provider:

```tsx theme={null}
import cookies from './.katla/cookies.json';

<KatlaProvider siteId="your-site-id" initialCookies={cookies}>
```

When `initialCookies` is provided, `useKatlaCookies()` returns the data immediately — no runtime fetch.

## Output structure

```
.katla/
  cookies.json            # default cookie data
  cookies.en-gb.json      # locale-specific cookie data
  cookies.en-us.json
  ...
  policy.en-gb.json       # one policy file per locale
  policy.en-us.json
  policy.de-de.json
  ...
  guard.js                # headless guard script
  manifest.json           # index of all generated files
```

The `manifest.json` file contains an index of all generated files:

```json theme={null}
{
  "siteId": "uuid",
  "domain": "example.com",
  "generatedAt": "2026-03-04T...",
  "files": {
    "cookies": {
      "default": "cookies.json",
      "en-gb": "cookies.en-gb.json",
      "en-us": "cookies.en-us.json"
    },
    "policy": {
      "en-gb": "policy.en-gb.json",
      "de-de": "policy.de-de.json"
    },
    "guard": "guard.js"
  }
}
```

## Using the guard script locally

The pulled `guard.js` file can be inlined instead of fetching from the CDN at runtime. Pass it as the `guardScript` prop:

**Vite (raw import):**

```tsx theme={null}
import cookies from './.katla/cookies.json';
import guardScript from './.katla/guard.js?raw';

<KatlaProvider siteId="your-site-id" initialCookies={cookies} guardScript={guardScript}>
```

**Next.js (read at build time):**

```tsx theme={null}
import { KatlaNextProvider } from '@katla.app/sdk/next';
import { getStaticGuardScript } from '@katla.app/sdk/next/server';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const guardScript = await getStaticGuardScript();

  return (
    <html lang="en">
      <body>
        <KatlaNextProvider siteId="your-site-id" guardScript={guardScript}>
          {children}
        </KatlaNextProvider>
      </body>
    </html>
  );
}
```

When `guardScript` is provided, the SDK injects the script content inline instead of adding a `<script src="...">` tag pointing to the CDN.

## CLI reference

```
katla pull [site-id] [options]

Options:
  -d, --dir <path>      Output directory (default: .katla)
  --base-url <url>      Override CDN base URL
  --locale <locale>     Pull a single locale only (default: all)
  --format <format>     Policy format: full, cookie, table (default: full)
  --help                Show this help message
```

The `site-id` is optional when a `katla.config.mjs` or `katla.config.js` file provides it.

## Programmatic API

You can also use `fetchStaticAll` directly in build scripts or server-side code:

```typescript theme={null}
import { fetchStaticAll } from '@katla.app/sdk/static';

const { cookies, policies, guard, manifest } = await fetchStaticAll({
  siteId: 'your-site-id',
  dir: '.katla',        // optional, default
  format: 'full',       // optional, default
  // locale: 'en-GB',   // optional, omit to pull all locales
});
```

For single-file fetching, `fetchStaticCookies` and `fetchStaticPolicy` are still available:

```typescript theme={null}
import { fetchStaticCookies } from '@katla.app/sdk/static';

const cookies = await fetchStaticCookies({
  siteId: 'your-site-id',
  outputPath: './public/cookies.json', // optional
});
```

See the [React guide](/react) and [Next.js guide](/nextjs) for full usage examples.

## Examples

<CardGroup cols={2}>
  <Card title="Vite static example" icon="github" href="https://github.com/katla-app/examples/tree/main/vite-sdk-static">
    Vite + React app using `katla pull` for build-time cookie data.
  </Card>

  <Card title="Next.js static example" icon="github" href="https://github.com/katla-app/examples/tree/main/nextjs-sdk-static">
    Next.js App Router using `katla pull` for build-time cookie data.
  </Card>
</CardGroup>
