Hi everyone,
Over the last few years I’ve built many sites with Kirby as a headless CMS, mostly with kirby-headless and KQL, and a TypeScript frontend on top (SvelteKit in my case). Every one of those projects ended up with the same thing: a makeshift KQL client with hand-written result types, a few helpers, and a lot of hoping that the types still matched what Kirby actually sent back. Rename a field, change a select, or hit an empty page, and the types happily lied to you.
I finally took the time to turn it into a proper library: kirby-kql-client.
If you use KQL in a type-safe frontend environment, this client is for you. You write the query exactly as you would for KQL. The client reads it and derives the result type from the query itself. You don’t write types by hand, and there’s no as const and no any.
Note: it currently works with Kirby 5 only (5.6 with KQL 3). Kirby 4 and older aren’t supported.
import { createClient } from 'kirby-kql-client'
const kirby = createClient({
url: 'https://example.com/api/kql', // kirby-headless, or /api/query for the KQL plugin
auth: { token: 'my-token' },
})
const news = await kirby.query({
query: "page('news').children.listed.sortBy('date', 'desc')",
select: { title: true, url: true, readingMinutes: 'page.minutes.toInt' },
})
// typeof news: { title: string; url: string; readingMinutes: number }[]
const project = await kirby.query({
query: "page('projects/alpha')",
select: {
title: true,
gallery: { query: 'page.images', select: ['url', 'alt'] },
author: { query: 'page.author.toUser', select: ['name'] },
},
})
// typeof project: {
// title: string
// gallery: { url: string; alt: string }[]
// author: { name: string } | null
// } | null
What you get
-
The query string is parsed and typed method by method, with the types Kirby actually returns:
page('…')can benull;childrenis a collection, so it’s an array;toIntis anumber,toFilecan benull, and a field is astring.
-
Selects, nested queries and pagination are typed too. A paginated result becomes
{ data, pagination }. -
Block types:
-
Kirby’s core blocks (heading, text, image, gallery, video, quote, list, code, markdown, line, table) are known out of the box.
-
You add your own blocks in one place.
block.type === 'film'then narrowsblock.content, in blocks fields and inside layouts:type Site = { blocks: { film: { film: string[]; autoplay: string } // your custom block } } const kirby = createClient<Site>({ url, auth })
-
-
Plugins: if a plugin adds page methods, field methods or whole new classes, you describe them once in a schema extension, and they’re typed like Kirby’s own.
-
Reusable queries: define a query once with
kql(…)and use its result type (Result<typeof query>) for component props, load functions and so on. -
Mistakes are caught at compile time. A query KQL can never answer, such as a method on a string, a typo in a root or a query string that doesn’t parse, is a compile error at the query. If you want, a strict mode turns unknown methods into errors too.
-
Both endpoints: the official KQL plugin (
/api/query, Basic auth) and kirby-headless (/api/kql, Bearer token). Content languages work through thelanguageoption. -
Small and portable:
- It runs wherever
fetchdoes: Node 18+, Bun, Deno, browsers and edge runtimes. You can pass in SvelteKit’sfetchin a load function. - It has no runtime dependencies and is ESM only.
- It runs wherever
Why you can trust the types
This was the part my makeshift clients never had:
- The types come from a schema generated directly from the Kirby 5.6 and KQL 3 source.
- The repo includes a small Kirby test site. Every result type is checked against the JSON that site really returns.
- CI regenerates everything and fails if the schema or the recorded responses drift.
That process turned up a few surprises. For example:
- A toggle inside a block is stored as
'true'/'false', not as a boolean. - A block without fields renders
content: [], not{}.
The client’s types reflect that, because they’re tested against reality, not against documentation.
Requirements
- Kirby 5 (tested on 5.6) with KQL 3.x, through the KQL plugin or kirby-headless. Kirby 4 and older aren’t supported yet.
- TypeScript 5.4 or later
Install
It’s still 0.x and not on npm yet. Install it from a release tag:
npm install github:the-leonat/kirby-kql-client#v0.2.0
pnpm add and bun add take the same specifier.
Docs and source: GitHub - the-leonat/kirby-kql-client: Typed client for Kirby's KQL: query results typed from the query itself · GitHub
The README has a lot more examples: query builders, pagination, schema extensions for plugins, block types and the known limitations.
I’m using it for a client site right now. If you try it and a query comes out typed wrong, please open an issue with the query and what your endpoint returned. That’s exactly the kind of case the test site is there to catch. Feedback and ideas are very welcome!