headquery
Typed, cacheable JavaScript clients for the REST APIs of headless PHP CMSs. You keep the CMS’s own query vocabulary (filters, sort, fields) and get TypeScript types generated from your content model.
Early development. headquery is still under development and should not be used in production yet. APIs, generated types and the schema format may change in any 0.x release.
import { createStatamicClient } from "@headquery/statamic";
import type { Schema } from "./cms.generated"; // generated from your content model
const cms = createStatamicClient<Schema>({
baseUrl: "https://cms.example.com",
});
const posts = await cms
.collections("blog") // collection handles autocomplete
.where("title", "contains", "monorepo") // only allowed_filters fields are accepted
.sort("-date")
.limit(10)
.fields(["title", "date", "hero"]) // narrows the result type
.get();
// GET /api/collections/blog/entries?fields=title,date,hero&filter[title:contains]=monorepo&limit=10&sort=-dateWhy another package for a fetch call? See Motivation.
How it works
- A small plugin on the CMS exports your content model (collections, fields, filters) as a CMS-neutral JSON schema.
headquery generateturns that schema into TypeScript types.- The client for your CMS compiles every query to a plain, cacheable
GETrequest against the CMS’s existing REST API, typed by the generated schema.
Principles
- Wraps the existing REST API. headquery is a thin layer over
fetch. It doesn’t add a new query engine on the server. - Prefers GET with deterministic URLs. The same query always produces the same URL, so browsers, CDNs and proxies can cache responses.
- Works untyped, better typed. Without generated types everything still works with loose types. Run the codegen and handles, filterable fields and result shapes are checked by TypeScript, without passing generics by hand.
- Zero runtime dependencies in the JS packages.
- Small by design. The Statamic client stays under 2.5 kB gzipped, including core; a size budget in CI keeps it there.
Packages
| Package | Registry | Purpose |
|---|---|---|
@headquery/core | npm | CMS-agnostic fetch transport with deterministic (cache-friendly) URLs |
@headquery/statamic | npm | Typed query builders for the Statamic REST Content API |
@headquery/codegen | npm | Generates TS types from a CMS schema (file or URL) |
@headquery/schema | npm | Types for the intermediate schema (IR) |
headquery/statamic | Packagist | Statamic addon: exports the content model via CLI or endpoint |
Last updated on