Multi-site
On a multi-site Statamic install, every query takes
.site(handle), which sends site=<handle>. With generated types, .site() only accepts the
handles of your sites:
const = await .("blog").("de").("-date").();
const = await .("blog").("hallo-headquery").("de").();
const = await .("settings").("de").();
const = await .("main").().("de").();.("blog").("dee");.site() takes the site’s handle from resources/sites.yaml (default, de), not its
language or locale.
Default site
Pass site to the client to send it with every query that supports it: entry and term lists,
find(), globals, and collection and nav trees. .site() still overrides it per query.
navs(), forms(), sites(), users() and assets() ignore site in Statamic, so they
don’t get it.
import { } from "@headquery/statamic";
const = ({ : "https://cms.example.com", : "de" });
const = await .("blog").("-date").(); // ?site=de&sort=-date
const = await .("blog").("hallo-headquery").(); // ?site=de
const = await .("blog").("default").(); // ?site=defaultThe default site becomes part of each query, so query.url() (and with it any cache key built
from it) is the same as with .site("de"). Unlike .site(), the client option accepts any string
(your handles are still suggested), so a runtime value fits as it is. In a framework with one
locale per request, create the client per request from the route’s locale, e.g. in Next.js with
next/root-params:
import { } from "@headquery/statamic";
// import { locale } from "next/root-params";
export async function () {
return ({ : ..!, : await () });
}
// app/[locale]/blog/[slug]/page.tsx: await (await cms()).collections("blog").where("slug", slug).first();An unknown handle is a 404 from Statamic. If your locales aren’t the site handles, map them:
import { , type } from "@headquery/statamic";
const = { : "default", : "de" } satisfies <string, >;
export function (: string) {
const = [ as keyof typeof ] ?? "default";
return ({ : ..!, });
}Typed site handles
The schema export (php please headquery:schema and the schema endpoint) always includes the
sites, also on single-site installs and independent of 'sites' => true in the API config.
headquery generate turns them into sites: "default" | "de" in the generated Schema. After
adding or renaming a site in Statamic, regenerate the types.
Use SiteHandle for your own code, e.g. a map of URL prefixes per site that has to cover every
site:
import type { } from "@headquery/statamic";
const = { : "", : "/de" } satisfies <, string>;Without generated types, or with types generated before site support, SiteHandle is string.
It comes from the generated file’s registration, not from the
client’s generic. Both are in the same file, so createStatamicClient<Schema>() gets typed
handles too, unless TypeScript resolves a second copy of @headquery/statamic (then
registration, and with it SiteHandle, doesn’t apply).
How Statamic handles site
| Endpoint | Without site | Unknown site |
|---|---|---|
| Entry and term lists | items of every site, mixed | 404 |
One entry or term (.find()) | default site | 404 (null with find()) |
globals(handle), collection and nav trees | default site | 404 |
globals() | default site | 500 (Statamic bug) |
navs(), forms(), sites(), users(), assets() | site is ignored | site is ignored |
Lists without site return the entries of all sites, counted together in meta.total. On a
multi-site install, pass .site() on every entry and term list:
// Both languages, mixed
const = await .("blog").();
// Only the default site
const = await .("blog").("default").();Entries:
- A localized entry has its own id and slug, plus
localeandorigin_id(the id of the entry it was localized from). - Fields that are not set in the localization are inherited from the origin.
.find(slug)looks the slug up in one site: the default site without.site(). Slugs of other sites are 404 (null)..find(id).site(handle)returns that site’s version of the entry, whether you pass the origin’s id or the id of another localization. It’snullwhen the entry isn’t localized in that site. That makes a language switcher one request per site:
import type { } from "@headquery/statamic";
async function (: string, : []) {
const = await .(
.(() => .("blog").().().(["title", "url"]).()),
);
return .(() => ( ? [.] : []));
}Terms, globals and trees:
- Terms keep their slug in every site; localized values fall back to the origin’s.
- Global sets return the site’s values; values that aren’t localized are inherited.
- Collection and nav trees are separate per site. Entry URLs (
url) include the site’s prefix (/de/blog/…).
Sites list
sites() lists the sites (GET /sites), but only with 'sites' => true in
config/statamic/api.php. handle is typed as SiteHandle; url has no trailing slash
(/de). For type-checking you don’t need it: the handles come from the schema export.