Register Your First Component

A catalog entry gives an existing React component a stable id and tells Dollie Editor that it may render it.

Start with one component you already trust in production. Keep its design, responsive behavior, and data boundaries in your application.

Create the component

type HeroProps = {
  headline?: string;
  description?: string;
  buttonLabel?: string;
};

export function Hero({
  headline = "Build pages within your product",
  description = "Give customers flexibility without giving up your design system.",
  buttonLabel = "Get started",
}: HeroProps) {
  return (
    <section className="px-6 py-24 text-center">
      <h1 className="text-5xl font-semibold">{headline}</h1>
      <p className="mx-auto mt-5 max-w-2xl text-lg">{description}</p>
      <button className="mt-8 rounded-md px-5 py-2.5">
        {buttonLabel}
      </button>
    </section>
  );
}

Register a catalog source

import {
  createCatalog,
  type CatalogSource,
} from "@dollie_ai/editor";

import { Hero } from "./hero";

export const appSource: CatalogSource = {
  id: "app",
  label: "My application",
  prefix: "app-",
  sections: [
    {
      id: "hero",
      name: "Hero",
      category: "hero",
      component: Hero,
      authorable: true,
    },
  ],
};

export const catalog = createCatalog([appSource]);

The stored component id is app-hero: the source prefix plus the local section id.

Define the editable fields

import type { BuilderSectionDefinition } from "@dollie_ai/editor";

export const appSectionDefinitions: BuilderSectionDefinition[] = [
  {
    id: "app-hero",
    name: "Hero",
    category: "hero",
    authorable: true,
    example: {},
    fields: [
      {
        kind: "text",
        key: "headline",
        label: "Headline",
        optional: true,
      },
      {
        kind: "text",
        key: "description",
        label: "Description",
        multiline: true,
        optional: true,
      },
      {
        kind: "text",
        key: "buttonLabel",
        label: "Button label",
        optional: true,
      },
    ],
  },
];

The definition id must match the prefixed component id exactly.

For a first component, writing three fields by hand makes the contract easy to understand. For a larger catalog, derive these definitions from TypeScript props and JSDoc with Generate Editable Fields.

Compose with the Core catalog

import { createCatalog } from "@dollie_ai/editor";
import {
  freeCatalog,
  freeSectionDefinitions,
} from "@dollie_ai/editor-catalog";

export const catalog = createCatalog([appSource, freeCatalog]);

export const sectionDefinitions = [
  ...appSectionDefinitions,
  ...freeSectionDefinitions,
];

Your application components and installed catalog packages can live in the same editor.

Check the boundary

Register a prop only when an editor user or Copilot should be allowed to change it.

Keep these concerns in the component or host:

• layout rules that protect the design;
• authenticated data access;
• tenant-sensitive choices;
• checkout or form behavior;
• server actions and secrets.

Next, Configure the Editor Runtime.