Skip to Content
CMSStatamicMulti-site

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");
Argument of type '"dee"' is not assignable to parameter of type '"default" | "de"'.

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

The 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

EndpointWithout siteUnknown site
Entry and term listsitems of every site, mixed404
One entry or term (.find())default site404 (null with find())
globals(handle), collection and nav treesdefault site404
globals()default site500 (Statamic bug)
navs(), forms(), sites(), users(), assets()site is ignoredsite 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 locale and origin_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’s null when 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.

Last updated on