Static cookies

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:

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

// 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:

katla pull

Or pass the site ID directly:

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:

{
  "scripts": {
    "prebuild": "katla pull",
    "build": "vite build"
  }
}

Then import the JSON and pass it to your provider:

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:

{
  "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):

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):

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:

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:

import { fetchStaticCookies } from '@katla.app/sdk/static';

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

See the React guide and Next.js guide for full usage examples.

Examples

Vite static example

Vite + React app using katla pull for build-time cookie data.

Next.js static example

Next.js App Router using katla pull for build-time cookie data.

Getting started

Guides

Reference

Compliance

Static cookies

Configuration file

CLI

Output structure

Using the guard script locally

CLI reference

Programmatic API

Examples

Vite static example

Next.js static example

​Configuration file

​CLI

​Output structure

​Using the guard script locally

​CLI reference

​Programmatic API

​Examples

Vite static example

Next.js static example

Configuration file

CLI

Output structure

Using the guard script locally

CLI reference

Programmatic API

Examples