headquery / statamic

0.2.0 2026-11-13 16:53 UTC

Requires

• php: ^8.2
• statamic/cms: ^5.0 || ^6.0

Requires (Dev)

• opis/json-schema: ^2.3
• orchestra/testbench: ^9.0 || ^10.0
• phpunit/phpunit: ^11.0

MIT

• rest
• headless
• typescript
• statamic
• codegen

Published on Packagist.org on 2026-11-13 16:58 UTC

README

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.

Statamic addon for headquery. It exports your content model so @headquery/codegen can generate TypeScript types for @headquery/statamic, the typed client for Statamic's REST Content API.

Read-only mirror. Issues and pull requests go to the headquery monorepo.

Install

composer require headquery/statamic
php artisan vendor:publish --tag=headquery-config   # optional

The REST API must be enabled in config/statamic/api.php. Only resources enabled there are exported, and only fields in allowed_filters are marked filterable.

Export via CLI (frontend in the same project)

php please headquery:schema --out=../frontend/headquery.schema.json
npx headquery generate --from ../frontend/headquery.schema.json --out ../frontend/src/cms.generated.ts

Export via endpoint (headless, frontend in another repo)

HEADQUERY_SCHEMA_ROUTE=true
HEADQUERY_SCHEMA_TOKEN=a-long-random-token

npx headquery generate \
  --base-url https://cms.example.com \
  --token "$HEADQUERY_SCHEMA_TOKEN" \
  --out src/cms.generated.ts

The endpoint returns 404 unless both variables are set, and 401 without the right bearer token. It sends an ETag, so unchanged schemas answer 304.

Custom fieldtypes

Unknown fieldtypes are exported as unknown. Map them in config/headquery.php (field_types) or dynamically:

use Headquery\Statamic\Schema\FieldMapper;

FieldMapper::extend('seo_pro', fn (array $config) => [
    'type' => 'object',
    'fields' => ['title' => ['type' => 'string'], 'description' => ['type' => 'string']],
]);