kirby-types

A collection of TypeScript types for Kirby CMS.

Quick Start •
Common Patterns •
Panel Types •
API Reference

When to Use

| Use Case | Types to Import |
| ------------------------------------------------------------ | ----------------------------------------------- |
| Fetching page data from Kirby's API | KirbyApiResponse, KirbyBlock, KirbyLayout |
| Building KQL queries with type safety | KirbyQueryRequest, KirbyQueryResponse |
| Developing Panel plugins (Vue components, custom fields) | Panel, PanelApi |
| Creating Writer extensions (rich text editor) | WriterMarkExtension, WriterNodeExtension |

Setup

``bash


pnpm

`ts
import type { KirbyQueryRequest, KirbyQueryResponse } from "kirby-types";

// Define your query with full type safety
const request: KirbyQueryRequest = {
query: "site",
select: {
title: true,
children: {
query: "site.children",
select: ["id", "title", "isListed"],
},
},
};

// Type the response
interface SiteData {
title: string;
children: { id: string; title: string; isListed: boolean }[];
}

type Response = KirbyQueryResponse;
`

$3

`ts
import type { KirbyBlock } from "kirby-types";

// Default block types are fully typed
const textBlock: KirbyBlock<"text"> = {
id: "abc123",
type: "text",
isHidden: false,
content: { text: "

Hello world

const heroBlock: KirbyBlock<"hero", HeroContent> = {
id: "def456",
type: "hero",
isHidden: false,
content: {
title: "Welcome",
image: "hero.jpg",
cta: "Learn more",
},
};
`

$3

`ts
import type { KirbyBlock, KirbyLayout } from "kirby-types";

const layout: KirbyLayout = {
id: "layout-1",
attrs: { class: "highlight" },
columns: [
{ id: "col-1", width: "1/3", blocks: [] },
{ id: "col-2", width: "2/3", blocks: [] },
],
};
`

Common Patterns

$3

`ts
import type { KirbyBlock, KirbyLayout, PanelModelData } from "kirby-types";

// Define custom block types alongside defaults
interface CallToActionContent {
text: string;
url: string;
style: "primary" | "secondary";
}

type CustomBlock =
| KirbyBlock<"text">
| KirbyBlock<"heading">
| KirbyBlock<"image">
| KirbyBlock<"cta", CallToActionContent>;

interface BlogPostContent {
date: string;
author: string;
blocks: CustomBlock[];
layout: KirbyLayout[];
}

type BlogPostPage = PanelModelData;
`

$3

`ts
import type { KirbyQueryRequest, KirbyQueryResponse } from "kirby-types";

// Define request
const request: KirbyQueryRequest = {
query: 'page("blog").children.listed',
select: {
title: "page.title",
date: "page.date.toDate",
excerpt: "page.text.toBlocks.excerpt(200)",
},
pagination: { limit: 10, page: 1 },
};

// Type the response data
interface BlogPostSummary {
title: string;
date: string;
excerpt: string;
}

// With pagination (second generic = true)
type PaginatedResponse = KirbyQueryResponse;

// Response shape:
// {
// code: 200,
// status: "ok",
// result: {
// data: BlogPostSummary[],
// pagination: { page, pages, offset, limit, total }
// }
// }
`

Panel Types

For Panel plugin development, type the global window.panel object:

`ts
import type { Panel } from "kirby-types";

declare global {
interface Window {
panel: Panel;
}
}
`

Common Panel operations:

`ts
// Notifications
window.panel.notification.success("Changes saved");
window.panel.notification.error("Something went wrong");

// Theme
window.panel.theme.set("dark");

// Navigation
await window.panel.view.open("/pages/blog");
await window.panel.dialog.open("/dialogs/pages/create");

// API calls
const page = await window.panel.api.pages.read("blog");
await window.panel.api.pages.update("blog", { title: "New Title" });

// Content state
const currentContent = panel.content.version("changes");
`

Advanced: Writer Extensions

For ProseMirror-based Writer extensions (requires optional peer dependencies):

`ts
import type { WriterMarkExtension } from "kirby-types";

const highlight: WriterMarkExtension = {
button: {
icon: "highlight",
label: "Highlight",
},
commands({ type, utils }) {
return () => utils.toggleMark(type);
},
inputRules({ type, utils }) {
return [utils.markInputRule(/\\([^]+)\\*$/, type)];
},
schema: {
parseDOM: [{ tag: "mark" }],
toDOM: () => ["mark", 0],
},
};
`

API Reference

$3

| Type | Description |
| -------------------------------------------- | ---------------------------------- |
| KirbyApiResponse | Standard API response wrapper |
| KirbyBlock | Block with type and content |
| KirbyLayout | Layout row with columns |
| KirbyLayoutColumn | Column with width and blocks |
| KirbyDefaultBlocks | Map of default block content types |
| KirbyDefaultBlockType | Union of default block type names |

$3

| Type | Description |
| -------------------------------------------- | ------------------------------------- |
| KirbyQueryRequest | KQL request with pagination |
| KirbyQueryResponse | KQL response with optional pagination |
| KirbyQuerySchema | KQL query schema structure |
| KirbyQuery | Valid KQL query string |
| ParseKirbyQuery | Parse query string to structured type |

$3

| Type | Description |
| ------------------------------------------ | ------------------------------- |
| Panel | Main Panel interface |
| PanelApi | API client methods |
| PanelState | Base state interface |
| PanelFeature | Feature with loading states |
| PanelModal | Modal (dialog/drawer) interface |
| PanelHelpers | Utility functions |

$3

| Type | Description |
| -------------------------------------------------- | ---------------------------------------- |
| KirbyFieldProps | Base field props from Field->toArray() |
| KirbyFieldsetProps | Fieldset from Fieldset->toArray() |
| KirbyBlocksFieldProps | Blocks field props with fieldsets |
| KirbyStructureFieldProps | Structure field props with nested fields |
| KirbyLayoutFieldProps | Layout field props with settings |
| KirbyAnyFieldProps | Union of all field prop types |

$3

| Type | Description |
| ------------------------------------------------ | ---------------------------------- |
| WriterEditor | Main editor instance |
| WriterMarkExtension | Mark extension interface |
| WriterNodeExtension | Node extension interface |
| WriterUtils | ProseMirror commands and utilities |

Optional Dependencies

Vue is an optional peer dependency for Panel types:

`bash
pnpm add -D vue@^2.7.0
``

License

MIT License © 2022-PRESENT Johann Schopplich