@glokki-cms/sdk

SDK for declaring blocks, globals, collections, and data-models that the glokki-cms editor consumes via its runtime handshake protocol.

Install

npm install @glokki-cms/sdk zod
# or
bun add @glokki-cms/sdk zod

zod is a peer dependency.

Usage

import { createBlockRegistry, defineBlock } from "@glokki-cms/sdk";
import { z } from "zod";

const Hero = defineBlock({
  type: "hero",
  label: "Hero",
  category: "content",
  schema: z.object({
    title: z.string(),
    subtitle: z.string().optional(),
  }),
  defaultProps: { title: "Hello" },
  Component: ({ title, subtitle }) => (
    <section>
      <h1>{title}</h1>
      {subtitle && <p>{subtitle}</p>}
    </section>
  ),
});

export const blocks = createBlockRegistry([Hero]);

The exported registry is sent to the CMS dashboard over the v2 iframe handshake; the dashboard renders props panels from the serialized Zod schema (FieldDescriptor[]) without ever needing the original Zod object.

Block categories

Declare the categories your blocks group into, in the order the CMS block picker should show them:

export const blockRegistry = createBlockRegistry(blocks, {
  categories: [
    { key: "parish", label: "Życie parafii" },
    { key: "content", label: "Treść" },
  ],
})

Order is the array's order. Keys and labels must be non-empty and at most 64 characters; keys may not contain whitespace. Declaring a list replaces the CMS's built-in categories rather than merging with them, and every block's category must appear in it — createBlockRegistry throws at build time otherwise.

Omit the option to keep the CMS's built-in five (content, layout, media, interactive, list).

Upgrade order. Custom category keys need a CMS that accepts them, and the categories only reach the CMS through @glokki-cms/react. Deploy the CMS first, then upgrade @glokki-cms/sdk to 0.15.0 and @glokki-cms/react to 0.9.0 together. An older CMS rejects the whole block registry on sync, not just the one block; an older react silently sends no categories at all.

See the glokki-cms docs for the full integration guide, global schemas, and delivery API contracts.

License

MIT