Skip to Content
Introduction

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=-date

Why another package for a fetch call? See Motivation.

How it works

  1. A small plugin on the CMS exports your content model (collections, fields, filters) as a CMS-neutral JSON schema.
  2. headquery generate turns that schema into TypeScript types.
  3. The client for your CMS compiles every query to a plain, cacheable GET request against the CMS’s existing REST API, typed by the generated schema.

Get started →

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

PackageRegistryPurpose
@headquery/corenpmCMS-agnostic fetch transport with deterministic (cache-friendly) URLs
@headquery/statamicnpmTyped query builders for the Statamic REST Content API
@headquery/codegennpmGenerates TS types from a CMS schema (file or URL)
@headquery/schemanpmTypes for the intermediate schema (IR)
headquery/statamicPackagistStatamic addon: exports the content model via CLI or endpoint
Last updated on