Integration Guide

npm install @glokki-cms/sdk @glokki-cms/react zod

bun add @glokki-cms/sdk @glokki-cms/react zod

/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ["@glokki-cms/react", "@glokki-cms/sdk"],
}

export default nextConfig

# Required
CMS_BASE_URL=http://localhost:3000    # URL where the CMS is running
CMS_TENANT=acme                       # Your tenant slug

# Required in production
APP_ENV=production                    # Anything else (or unset) = noindex, nofollow

# Recommended
CMS_API_KEY=ek_live_...               # Delivery API key (Settings → API Keys)
NEXT_PUBLIC_SITE_URL=https://acme.com # Public URL of your site (for SEO)
NEXT_PUBLIC_CMS_TENANT=acme           # Same as CMS_TENANT, readable in client code (editor tenant guard)

# Optional
CMS_REVALIDATE_SECRET=your-secret     # HMAC secret for on-demand revalidation

// lib/cms.ts
import { createClient } from "@glokki-cms/sdk"
import { cache } from "react"

export const cmsConfig = {
  baseUrl: process.env.CMS_BASE_URL ?? "http://localhost:3000",
  apiKey: process.env.CMS_API_KEY,
  tenantSlug: process.env.CMS_TENANT ?? "acme",
} as const

export const cms = createClient({
  ...cmsConfig,
  fetchInit: { next: { tags: ["cms-pages"] } }, // Enables on-demand revalidation
})

// Deduplicate identical calls within a single server render pass
export const getPageBySlug = cache((slug: string) => cms.pages.getBySlug(slug))

// Pages
const page = await cms.pages.getBySlug("/about")
const { data, meta } = await cms.pages.list({ locale: "en", limit: 10 })

// Navigation
const nav = await cms.navigation.get({ locale: "en" })

// Redirects
const redirects = await cms.redirects.list()

// Collections
const { data } = await cms.collections.list()
const collection = await cms.collections.getBySlug("blog")
const { entries, pagination } = await cms.collections.listEntries("blog", {
  limit: 20,
  offset: 0,
})

// A/B Testing
const variant = await cms.experiments.resolveVariant(experimentId, visitorId)
await cms.experiments.recordConversion(experimentId, visitorId)

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

const heroSchema = z.object({
  heading: z
    .string()
    .min(1)
    .max(120)
    .default("Welcome to our site")
    .describe("Heading"),
  subheading: z.string().max(240).optional().describe("Subheading"),
  backgroundImage: z
    .string()
    .url()
    .optional()
    .meta({ fieldType: "image" })
    .describe("Background Image"),
  ctaLabel: z.string().max(60).optional().describe("CTA Label"),
  ctaUrl: z.string().url().default("#").describe("CTA URL"),
  alignment: z
    .enum(["left", "center", "right"])
    .default("center")
    .describe("Alignment"),
})

type HeroProps = z.infer<typeof heroSchema>

function HeroComponent({
  heading = "Welcome to our site",
  subheading,
  backgroundImage,
  ctaLabel,
  ctaUrl = "#",
  alignment = "center",
}: HeroProps) {
  return (
    <section className="flex min-h-[400px] flex-col justify-center px-8 py-16">
      <h1 className="text-4xl font-bold">{heading}</h1>
      {subheading && <p className="mt-4 text-lg opacity-80">{subheading}</p>}
      {ctaLabel && (
        <a
          href={ctaUrl}
          className="mt-6 inline-flex rounded-md bg-accent px-6 py-2.5 font-medium"
        >
          {ctaLabel}
        </a>
      )}
    </section>
  )
}

export const HeroBlock = defineBlock({
  type: "hero",
  label: "Hero",
  category: "content",
  icon: "Sparkles",
  description: "Full-width banner with heading and CTA",
  defaultProps: {
    heading: "Welcome to our site",
    ctaUrl: "#",
    alignment: "center",
  },
  propsSchema: heroSchema,
  component: HeroComponent,
})

// blocks/registry.ts
import { createBlockRegistry } from "@glokki-cms/sdk"
import type { ComponentType } from "react"

import { CtaBlock } from "./cta"
import { HeroBlock } from "./hero"
import { RichTextBlock } from "./rich-text"

export const blockRegistry = createBlockRegistry([
  HeroBlock,
  CtaBlock,
  RichTextBlock,
])

// Derive a component Map for the renderer
export const registry: Map<
  string,
  ComponentType<Record<string, unknown>>
> = new Map(
  blockRegistry
    .getTypes()
    .map((type) => [
      type,
      blockRegistry.getComponent(type) as ComponentType<
        Record<string, unknown>
      >,
    ])
)

export const blockRegistry = createBlockRegistry(
  [HeroBlock, CtaBlock, RichTextBlock],
  {
    categories: [
      { key: "parish", label: "Parish life" },
      { key: "content", label: "Content" },
    ],
  }
)

// app/[[...slug]]/page.tsx
import { CMSPage } from "@glokki-cms/react"
import { EDITOR_QUERY_PARAM } from "@glokki-cms/sdk"
import { notFound } from "next/navigation"

import { EditorShell } from "@/blocks/editor-shell"
import { registry } from "@/blocks/registry"
import { getPageBySlug } from "@/lib/cms"

type PageProps = {
  params: Promise<{ slug?: string[] }>
  searchParams: Promise<Record<string, string | string[] | undefined>>
}

export default async function CmsPage({ params, searchParams }: PageProps) {
  const [{ slug }, search] = await Promise.all([params, searchParams])
  const pageSlug = slug ? `/${slug.join("/")}` : "/"
  const isEditorMode = search[EDITOR_QUERY_PARAM] === "1"

  // Editor mode: render the visual editor shell (see Step 7)
  if (isEditorMode) {
    return <EditorShell pageSlug={pageSlug} />
  }

  const page = await getPageBySlug(pageSlug)
  if (!page) notFound()

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

// blocks/editor-shell.tsx
"use client"

import { CMSPageEditor, VisualEditorProvider } from "@glokki-cms/react"
import type { ComponentNode } from "@glokki-cms/sdk"

import { layoutRegistry } from "@/layouts/registry"
import { blockRegistry, registry } from "./registry"

export function EditorShell({
  pageSlug,
  fallbackTree,
}: {
  pageSlug: string
  fallbackTree?: ComponentNode[]
}) {
  return (
    <VisualEditorProvider
      registry={registry}
      blockRegistry={blockRegistry}
      layoutRegistry={layoutRegistry}
      fallbackTree={fallbackTree}
      pageSlug={pageSlug}
      tenantSlug={process.env.NEXT_PUBLIC_CMS_TENANT}
    >
      <CMSPageEditor />
    </VisualEditorProvider>
  )
}

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

function MyComponent() {
  const {
    componentTree, // Current block tree
    selectedBlockId, // Currently selected block (or null)
    viewport, // "desktop" | "tablet" | "mobile"
    isEditorMode, // true when inside the CMS iframe
    isTreeSynced, // true after first tree:update from CMS
    editorOrigin, // CMS origin (null when not in editor mode)
  } = useVisualEditor()
}

// middleware.ts
import { EDITOR_QUERY_PARAM } from "@glokki-cms/sdk"
import { type NextRequest, NextResponse } from "next/server"

const cmsOrigin = (() => {
  const base = process.env.CMS_BASE_URL || "http://localhost:3000"
  try {
    return new URL(base).origin
  } catch {
    return base
  }
})()

export default function middleware(request: NextRequest) {
  const isEditorMode =
    request.nextUrl.searchParams.get(EDITOR_QUERY_PARAM) === "1"
  const response = NextResponse.next()

  if (isEditorMode) {
    // Allow the CMS to embed this page in an iframe
    response.headers.set(
      "Content-Security-Policy",
      `frame-ancestors 'self' ${cmsOrigin}`
    )
    // Remove X-Frame-Options as it takes precedence in older browsers
    response.headers.delete("X-Frame-Options")
  } else {
    // Prevent clickjacking on public pages
    response.headers.set("X-Frame-Options", "SAMEORIGIN")
  }

  return response
}

https://acme.com/about?_editor=1&_editorToken=<token>&_editorOrigin=https://cms.editor.app

// lib/preview.ts
import { createClient } from "@glokki-cms/sdk"
import { cmsConfig } from "./cms"

type PreviewParams =
  | { isPreview: true; token: string }
  | { isPreview: false; token: undefined }

export function parsePreviewParams(
  searchParams: Record<string, string | string[] | undefined>
): PreviewParams {
  const preview = searchParams.preview
  const token =
    typeof searchParams.token === "string" ? searchParams.token : undefined
  if (preview === "true" && token) {
    return { isPreview: true, token }
  }
  return { isPreview: false, token: undefined }
}

export function createPreviewClient(token: string) {
  return createClient({
    ...cmsConfig,
    preview: true,
    previewToken: token,
    fetchInit: { cache: "no-store" }, // Never cache preview content
  })
}

// In app/[[...slug]]/page.tsx
import { PreviewBanner } from "@glokki-cms/react"
import { createPreviewClient, parsePreviewParams } from "@/lib/preview"

// Inside your page component:
const { isPreview, token } = parsePreviewParams(search)

const page = isPreview
  ? await createPreviewClient(token).pages.getBySlug(pageSlug)
  : await getPageBySlug(pageSlug)

if (!page) notFound()

// Render with preview banner:
return (
  <>
    {isPreview && <PreviewBanner />}
    <CMSPage componentTree={page.componentTree} registry={registry} />
  </>
)

// app/api/revalidate/route.ts
import crypto from "node:crypto"
import { revalidatePath, revalidateTag } from "next/cache"

export async function POST(request: Request) {
  const secret = process.env.CMS_REVALIDATE_SECRET
  if (!secret) {
    return Response.json(
      { error: "CMS_REVALIDATE_SECRET not configured" },
      { status: 500 }
    )
  }

  // Verify HMAC-SHA256 signature
  const timestamp = request.headers.get("X-Editor-Timestamp")
  const signature = request.headers.get("X-Editor-Signature")
  if (!timestamp || !signature) {
    return Response.json(
      { error: "Missing signature headers" },
      { status: 401 }
    )
  }

  const body = await request.text()
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex")

  const sigBuf = Buffer.from(signature)
  const expectedBuf = Buffer.from(expected)
  if (
    sigBuf.length !== expectedBuf.length ||
    !crypto.timingSafeEqual(sigBuf, expectedBuf)
  ) {
    return Response.json({ error: "Invalid signature" }, { status: 401 })
  }

  const payload = JSON.parse(body) as { slug?: string }
  const path = payload.slug ? `/${payload.slug}` : "/"

  revalidateTag("cms-pages")
  revalidatePath(path)

  return Response.json({ revalidated: true, path })
}

// app/[[...slug]]/page.tsx
import { cmsMetadata } from "@glokki-cms/react"
import type { Metadata } from "next"

export async function generateMetadata({
  params,
  searchParams,
}: PageProps): Promise<Metadata> {
  const [{ slug }, search] = await Promise.all([params, searchParams])
  const { isPreview } = parsePreviewParams(search)

  // Prevent preview pages from being indexed
  if (isPreview) {
    return { robots: { index: false, follow: false } }
  }

  const pageSlug = slug ? `/${slug.join("/")}` : "/"
  const page = await getPageBySlug(pageSlug)
  return cmsMetadata(page, { baseUrl: process.env.NEXT_PUBLIC_SITE_URL })
}

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

// Inside your page component:
;<JsonLd data={page.seo.jsonLd} />

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

const cms = createClient({
  baseUrl: "https://cms.editor.app",
  apiKey: "ek_live_...",
  tenantSlug: "acme",
})

// Fetch pages in your data layer (e.g., React Router loader, useEffect, etc.)
const page = await cms.pages.getBySlug("/about")

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

function Page({ page }) {
  return <CMSPage componentTree={page.componentTree} registry={registry} />
}

import { CMSPageEditor, VisualEditorProvider } from "@glokki-cms/react"
import { EDITOR_QUERY_PARAM } from "@glokki-cms/sdk"
import { blockRegistry, registry } from "./blocks/registry"
import { layoutRegistry } from "./layouts/registry"

function Page({ page, slug }) {
  const params = new URLSearchParams(window.location.search)
  const isEditorMode = params.get(EDITOR_QUERY_PARAM) === "1"

  if (isEditorMode) {
    return (
      <VisualEditorProvider
        registry={registry}
        blockRegistry={blockRegistry}
        layoutRegistry={layoutRegistry}
        pageSlug={slug}
      >
        <CMSPageEditor />
      </VisualEditorProvider>
    )
  }

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

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

const metadata = cmsMetadata(page, { baseUrl: "https://acme.com" })
// metadata.title, metadata.description, metadata.openGraph, etc.