Components

This page covers how the component registry works, what happens to unmatched components, and how to add a new block to the site.

The registryCopy Anchor Link

In the site template, the only place that connects a CMS component to a React component is the COMPONENT_REGISTRY object in src/components/cms/DynamicComponent.tsx.

const COMPONENT_REGISTRY = {
  "top-banner": () => Promise.resolve(null),
  custom: () => import("./CustomComponent"),
  "markdown-content": () => import("./MarkdownContent"),
  form: () => import("./FormContainer"),
} as const;

Each key is a component slug. Each value is an import() function that lazy-loads the component.

Matching orderCopy Anchor Link

DynamicComponent looks at the node's slug first. If there is no slug, it uses the lowercased componentType. Keys are compared in lowercase.

Built-in blocksCopy Anchor Link

Props passed to the componentCopy Anchor Link

DynamicComponent passes every field of the node as props: children, data, uniqueId, slug, title, and the rest. It also adds pageData, which is the page response itself plus a shareUrl field. Ignore the fields you don't need.

Unmatched componentsCopy Anchor Link

If a component's import() fails, a red Error loading component box is rendered in its place and the error is written to the server log.

Adding a new blockCopy Anchor Link

The whole contract is one registry line and one file under src/components/cms/. There is no other place to register anything.

import type { ApiComponent } from "@/types/cms";

interface HeroBannerProps {
  children?: ApiComponent[];
  pageData?: Record<string, unknown>;
  [key: string]: unknown; // ignore fields you don't use
}

const pick = (c: ApiComponent[] | undefined, slug: string) =>
  c?.find((x) => x.slug === slug)?.data as string | undefined;

export default function HeroBanner({ children }: HeroBannerProps) {
  const title = pick(children, "title");
  if (!title) return null; // missing data: render nothing

  const description = pick(children, "description");

  return (
    <section className="py-16">
      <h1 className="text-4xl font-bold">{title}</h1>
      {description && <p className="mt-4 text-muted-foreground">{description}</p>}
    </section>
  );
}

const COMPONENT_REGISTRY = {
  // …
  "hero-banner": () => import("./HeroBanner"),
} as const;

Inspector supportCopy Anchor Link

On the preview site, the panel can select a component when you click it on the page. DynamicComponent already marks every top-level block. To make inner elements selectable too, spread cmpAttrs onto them:

import { cmpAttrs } from "@/lib/inspector";

// …
<li key={item.uniqueId} {...cmpAttrs(item.uniqueId, item.slug)}>
  {/* … */}
</li>

cmpAttrs returns an empty object when NEXT_PUBLIC_INSPECTOR_ENABLED is off, so no attributes reach the live site.

TipsCopy Anchor Link

• Any field can be missing. Components carry their own defaults.
• Find children by slug, not by position.
• Use uniqueId as the key in lists, not id.
• Add "use client" only when you need state, effects, or a browser API.