API Reference

For step-by-step integration instructions, see the Integration Guide. For block development patterns, see the Block Development Guide.

@glokki-cms/sdk

defineBlock()

The primary SDK API for block registration. Declares a block with metadata, a Zod schema, and a React component. Auto-serializes the Zod schema into FieldDescriptor[] so the CMS never touches Zod directly.

import { defineBlock } from "@glokki-cms/sdk"

Signature

function defineBlock<TSchema, TComponent>(
  config: DefineBlockConfig<TSchema, TComponent>
): BlockRegistryEntry<InferOutput<TSchema>, TComponent>

DefineBlockConfig

Returns

A BlockRegistryEntry with pre-serialized fields: FieldDescriptor[], ready for createBlockRegistry().

Example

import { z } from "zod"
import { defineBlock } from "@glokki-cms/sdk"
import { HeroComponent } from "./hero"

const heroSchema = z.object({
  heading: z.string().min(1).max(120).describe("Heading"),
  subheading: z.string().max(240).optional().describe("Subheading"),
  alignment: z.enum(["left", "center", "right"]).default("center"),
})

export const HeroBlock = defineBlock({
  type: "hero",
  label: "Hero",
  category: "content",
  icon: "Sparkles",
  defaultProps: {
    heading: "Hello World",
    alignment: "center",
  },
  propsSchema: heroSchema,
  component: HeroComponent,
})

Errors

Throws if propsSchema is not a z.object() schema (e.g., z.record(), z.string()). Only z.object() schemas can be serialized into field descriptors.

createBlockRegistry()

Creates a typed block registry from an array of defineBlock() results. The registry provides component lookup, wire-safe serialized definitions for the iframe handshake, and type introspection.

import { createBlockRegistry } from "@glokki-cms/sdk"

Signature

function createBlockRegistry(
  entries: BlockRegistryEntry[],
  options?: BlockRegistryOptions
): BlockRegistry

BlockRegistryOptions

A declared list replaces the CMS's built-in categories — it never merges with them — and the block picker renders the categories in the array's order. Keys and labels must be non-empty and at most 64 characters, and a key may not contain whitespace. Every block's category must appear in the list; createBlockRegistry throws at build time otherwise.

BlockRegistry

Example

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

const HeroBlock = defineBlock({ type: "hero" /* ... */ })
const CtaBlock = defineBlock({ type: "cta" /* ... */ })

const registry = createBlockRegistry([HeroBlock, CtaBlock], {
  categories: [
    { key: "content", label: "Content" },
    { key: "interactive", label: "Interactive" },
  ],
})

registry.getTypes() // ["hero", "cta"]
registry.getComponent("hero") // HeroComponent
registry.getSerializedDefinitions() // SerializedBlockDefinition[]
registry.getCategories() // the two declared categories, in order

Errors

Throws if duplicate block types are detected in the entries array, and — when categories is declared — if the list is empty, holds a duplicate key, has an invalid key or label, or omits a category that one of the blocks names.

createClient()

Creates a typed client for the CMS Delivery API. Supports fetching pages, navigation, redirects, A/B experiment resolution, and collections.

import { createClient } from "@glokki-cms/sdk"

Signature

function createClient(options: ClientOptions): CMSClient

ClientOptions

The fetchInit option lets you control Next.js caching behavior:

// Always fresh (disables ISR/SSG)
createClient({ baseUrl, fetchInit: { cache: "no-store" } })

// On-demand revalidation via tags
createClient({ baseUrl, fetchInit: { next: { tags: ["cms"] } } })

// ISR with 60-second TTL
createClient({ baseUrl, fetchInit: { next: { revalidate: 60 } } })

CMSClient

The client object returned by createClient() exposes these namespaces:

client.pages

client.navigation

client.redirects

client.experiments

client.collections

ListCollectionEntriesOptions

Field filters. fields (or ?field.<key>=<value> on the raw endpoint) filters on custom fields that are sortable, shown in the list, or filterable. Text fields match partially, select/boolean exactly, and date/number fields accept <key>_gte / <key>_lte. Data model reference fields accept a record UUID or a record key ({ topics: "seo" }); a multi reference (dataModelRefs) matches entries that contain the record. A key that matches no record returns an empty list rather than ignoring the filter. Repeating a parameter on the raw endpoint (?field.topics=seo&field.topics=performance) requires all of them.

Example

const cms = createClient({
  baseUrl: process.env.CMS_BASE_URL!,
  tenantSlug: process.env.CMS_TENANT!,
  apiKey: process.env.CMS_API_KEY!,
  fetchInit: { next: { tags: ["cms-pages"] } },
})

// Fetch a page
const page = await cms.pages.getBySlug("about")

// List pages
const { data: pages, meta } = await cms.pages.list({ limit: 10 })

// Collections
const { entries } = await cms.collections.listEntries("blog", {
  page: 1,
  limit: 10,
  sortBy: "published_at",
  sortDirection: "desc",
  tag: "featured",
})

CMSError

Error class thrown when the Delivery API returns an error response.

import { CMSError } from "@glokki-cms/sdk"

Properties

Example

try {
  // Note: pages.getBySlug() returns null for 404, not an error.
  // CMSError is thrown for non-404 errors like auth failures.
  const nav = await cms.navigation.get()
} catch (error) {
  if (error instanceof CMSError) {
    console.log(error.code) // "UNAUTHORIZED"
    console.log(error.status) // 401
  }
}

serializeBlockSchema()

Low-level utility that converts a Zod z.object() schema into FieldDescriptor[]. Used internally by defineBlock() — you typically don't need to call this directly.

import { serializeBlockSchema } from "@glokki-cms/sdk"

Signature

function serializeBlockSchema(schema: ZodObjectSchema): FieldDescriptor[]

@glokki-cms/react

VisualEditorProvider

Context provider that manages visual editor state. In normal mode, renders the fallbackTree with zero overhead. In editor mode (when loaded inside the CMS iframe), initiates a postMessage handshake with the CMS and syncs the component tree, selection, and viewport in real-time.

import { VisualEditorProvider } from "@glokki-cms/react"

Props (VisualEditorProviderProps)

Behavior

• Normal mode: Uses fallbackTree as the component tree. No postMessage bridge overhead.
• Editor mode (detected via ?_editor=1&_editorOrigin=... query params): Initiates handshake with the CMS, then receives tree:update, block:select, viewport:change, block:props-update, block:scroll-into-view, and token:refresh messages.

Example

<VisualEditorProvider
  registry={registry}
  blockRegistry={blockRegistry}
  layoutRegistry={layoutRegistry}
  fallbackTree={page.componentTree}
  pageSlug="/about"
  tenantSlug={process.env.NEXT_PUBLIC_CMS_TENANT}
>
  <CMSPageEditor />
</VisualEditorProvider>

useVisualEditor()

Hook that reads the visual editor context. Must be called within a <VisualEditorProvider>.

import { useVisualEditor } from "@glokki-cms/react"

Signature

function useVisualEditor(): VisualEditorContextValue

VisualEditorContextValue

Example

function MyBlock() {
  const { isEditorMode, selectedBlockId, viewport } = useVisualEditor()

  return (
    <div>
      {isEditorMode && <span>Editing</span>}
      {viewport === "mobile" && <MobileLayout />}
    </div>
  )
}

Errors

Throws if called outside a <VisualEditorProvider>.

CMSPageEditor

Editor-aware page renderer. Reads the component tree from VisualEditorContext, wraps each block in <EditableBlock> for click/hover selection, and renders <InsertionIndicator> and <BlockGapInserter> for visual insertion feedback.

import { CMSPageEditor } from "@glokki-cms/react"

Props

None. Reads all state from VisualEditorContext.

Behavior

• Renders each block using the component registry with interactive editing wrappers
• Shows an empty canvas placeholder when the tree is empty (editor mode only)
• Renders insertion indicators at the computed insertion position when the block library is open
• Reports tree:rendered back to the CMS after each render cycle

Example

<VisualEditorProvider registry={registry} pageSlug="/about">
  <CMSPageEditor />
</VisualEditorProvider>

CMSPage

Static page renderer for non-editor contexts. Renders a component tree using a registry without any editor interactivity. Use this for published page rendering.

import { CMSPage } from "@glokki-cms/react"

Props

Example

<CMSPage componentTree={page.componentTree} registry={registry} />

PreviewBanner

Amber warning banner displayed at the top of the viewport during preview mode. Shows "Preview mode --- this page is not published" with a dismiss button. Uses inline styles so tenant apps don't need Tailwind or any CSS framework.

import { PreviewBanner } from "@glokki-cms/react"

Props

None.

Example

export default async function Page({ searchParams }) {
  const { preview } = await searchParams
  const isPreview = preview === "true"
  return (
    <>
      {isPreview && <PreviewBanner />}
      <MainContent />
    </>
  )
}

cmsMetadata()

Generates a Next.js Metadata object from a CMS page's SEO data. Handles title, description, canonical URL, robots, Open Graph, Twitter Card, and hreflang alternates.

import { cmsMetadata } from "@glokki-cms/react"

Signature

function cmsMetadata(
  page: DeliveryPage | null,
  options?: CmsMetadataOptions
): Metadata

CmsMetadataOptions

Behavior

• Returns { title: "Page not found", robots: { index: false } } when page is null
• Non-production is always noindex, nofollow. Unless env (or APP_ENV) is exactly "production", robots are forced to { index: false, follow: false } so staging and preview deploys are never indexed. Set APP_ENV=production on your production deployment, or every page will be de-indexed. In production, the page's stored robots string is honoured ("none" = noindex, nofollow)
• JSON-LD is not included (Next.js Metadata API does not support it). Use the <JsonLd> component separately

Example

import { cmsMetadata, JsonLd } from "@glokki-cms/react"

export async function generateMetadata({ params }) {
  const { slug } = await params
  const page = await cms.pages.getBySlug(slug)
  return cmsMetadata(page, { baseUrl: "https://acme.editor.app" })
}

export default async function Page({ params }) {
  const { slug } = await params
  const page = await cms.pages.getBySlug(slug)
  return (
    <>
      <JsonLd data={page.seo.jsonLd} />
      <CMSPage componentTree={page.componentTree} registry={registry} />
    </>
  )
}

JsonLd

Renders JSON-LD structured data as <script type="application/ld+json"> tags. Escapes closing script tags to prevent XSS. Each item in the array becomes a separate script tag.

import { JsonLd } from "@glokki-cms/react"

Props

Renders nothing when data is undefined or an empty array, so you can pass page.seo.jsonLd without a guard.

Example

<JsonLd data={page.seo.jsonLd} />

FormBlock

Client component that renders a form built in the CMS (Forms), validates it in the browser, and submits it to the Delivery API. Field definitions, the success message, the redirect URL, and spam protection (honeypot, optional Turnstile/reCAPTCHA) come from the form's settings in the CMS.

import { FormBlock } from "@glokki-cms/react"

Props

Validation messages and the loading text are English and not yet configurable.

Styling

The component renders unstyled markup with stable hooks: the root carries data-form-block and data-status (loading, ready, submitting, success, error); the button has data-form-submit, and a submission error is a data-form-error element with role="alert".

Example

The form fetches and submits from the browser, so the client needs a key there: use a delivery key (delivery:read scope), which is meant to be public, and keep admin keys server-side.

"use client"

import { FormBlock } from "@glokki-cms/react"
import { createClient } from "@glokki-cms/sdk"

const client = createClient({
  baseUrl: process.env.NEXT_PUBLIC_CMS_BASE_URL!,
  tenantSlug: process.env.NEXT_PUBLIC_CMS_TENANT!,
  apiKey: process.env.NEXT_PUBLIC_CMS_API_KEY!,
})

export function ContactForm({ formId }: { formId: string }) {
  return (
    <FormBlock
      client={client}
      formId={formId}
      submitLabel="Send message"
      submittingLabel="Sending…"
    />
  )
}

CdnImage

Renders an image prop served through your /cdn/ route with a responsive srcSet and the asset's focal point. Any non-/cdn/ URL renders as a plain <img>. Since 0.10.0. Props and the generated markup are described in Asset CDN Proxy.

import { CdnImage } from "@glokki-cms/react"

;<CdnImage
  src={image}
  alt={alt}
  width={1200}
  height={800}
  sizes="(min-width: 768px) 50vw, 100vw"
/>

createComponentRegistry()

Deprecated. Use createBlockRegistry() from @glokki-cms/sdk instead.

Creates a simple Map<string, Component> from a plain object. Does not support the v2 handshake, block metadata, or dynamic slots.

import { createComponentRegistry } from "@glokki-cms/react"

Signature

function createComponentRegistry(
  components: Record<string, ComponentType<Record<string, unknown>>>
): ComponentRegistry

Migration

// Before (deprecated)
const registry = createComponentRegistry({
  hero: HeroComponent,
  cta: CtaComponent,
})

// After (recommended)
import { defineBlock, createBlockRegistry } from "@glokki-cms/sdk"

const HeroBlock = defineBlock({ type: "hero", ..., component: HeroComponent })
const CtaBlock = defineBlock({ type: "cta", ..., component: CtaComponent })
const registry = createBlockRegistry([HeroBlock, CtaBlock])

Additional Exports

The packages export several additional utilities and components beyond the primary APIs documented above. These are typically used for advanced integrations or internal purposes.

@glokki-cms/sdk — Additional

@glokki-cms/react — Additional

SDK Types

Key types exported from @glokki-cms/sdk:

Block Types

Delivery API Types

Collection Types

Field Descriptor Types

Visual Editor Protocol Types

| Type | Description | | --------------------- | -------------------------------------------------- | --- | | VisualEditorMessage | Base message type for CMS <-> iframe communication | | ProtocolVersion | Protocol version number (1 | 2) | | CMSToIframeMessage | Union of all message types from CMS to iframe | | IframeToCMSMessage | Union of all message types from iframe to CMS | | Viewport | "desktop" \| "tablet" \| "mobile" |

Protocol Constants

React Types

Key types exported from @glokki-cms/react: