Skip to Content
ClientTypes

Types

headquery works untyped and gets better typed: without generated types every handle and field is accepted, and with them TypeScript checks handles, filterable fields and result shapes.

The explicit generic

Pass the generated Schema to the client, as the client file from headquery init does:

import { } from "@headquery/statamic"; import type { Schema } from "./cms.generated"; export const = <Schema>({ : "https://cms.example.com" });

Collection handles autocomplete, .where() only accepts filterable fields, and .fields() narrows results.

The explicit generic also lets you talk to two CMS instances: generate one file per instance (one config file each, passed with --config) and pass each Schema to its own client.

Registration

The generated file also registers its Schema through module augmentation:

declare module "@headquery/statamic" { interface Register { schema: Schema; } }

So importing the file once (import "./cms.generated") types createStatamicClient() without the generic. That relies on TypeScript seeing the generated file and resolving the same @headquery/statamic copy, so the explicit generic is the more robust default.

Without generated types

Without a registered or passed schema, the client falls back to loose types: any handle, any field, items typed as { id: string } & Record<string, unknown>.

Generated names

The generated file declares one interface per resource (BlogEntry, TagsTerm, SettingsGlobal, …), which you can import for props and helpers. How CMS fields map to TypeScript is listed per CMS, e.g. Statamic field types.

Using the types in your own code

For props, helpers and components, import the named types from the generated file. They are the most precise, and a missing or moved file is a compile error:

import type { BlogEntry } from "./cms.generated"; export function (: <BlogEntry, "title" | "url">) { return `${.} → ${. ?? "#"}`; }

Code that shouldn’t depend on the generated file’s path, like shared components or a package in a monorepo, can use the registered schema from the adapter instead: RegisteredSchema is the registered Schema, SiteHandle its site handles.

import type { , } from "@headquery/statamic"; type = ["collections"]["blog"]["item"]; const = { : "English", : "Deutsch" } satisfies <, string>;

Both come from the registration, so they fall back to loose types (LooseSchema, string) wherever it doesn’t apply: when the generated file isn’t part of the TypeScript program, or a second copy of @headquery/statamic is resolved.

Last updated on