Catalogs Overview

A catalog is the allowlist that makes Dollie Editor predictable.

It can contain:

• sections;
• illustrations and widgets;
• editable field definitions;
• templates;
• concise AI guidance.

Your application can compose local sources and installed catalog packages:

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

Source or package

Use a CatalogSource for components owned directly by the current application.

Use a CatalogPackage when content should travel as a unit with definitions, templates, version metadata, and agent guidance.

Describe how a component should be used

A section summary should explain its intended job, the main customisable props, and the space and visual content its slots suit. An illustration description should explain the product moment, which content can actually change, and whether its meaningful details need a wide section or remain clear in a small tile.

Check the rendered component with representative content before making placement claims. A dashboard that scales into a column may fit technically while its text becomes unreadable. Note deliberate masks and cropping, distinguish decorative media from readable product proof, and avoid claiming a fixed scene has configurable content. Exact minimum widths need a visual check at that width.

Keep this guidance in source metadata or hand-written description overrides, then regenerate the host manifest. Do not edit a generated manifest directly. Field schemas describe valid input; descriptions explain useful composition. Neither replaces inspecting the finished page in the host preview.

Stable ids matter

Every source id and prefix must be unique. Stored pages refer to final prefixed ids, so changing a prefix is a content migration.

Inspect the current installed inventory with:

npx dollie-editor info --json

Package discovery lists installed catalogue packages. For the exact inventory registered by an application, including its own sections, illustration props, and image library, point the CLI at the same generated manifest the host uses:

{
  "x-dollie-editor": {
    "manifests": {
      "page": "resources/editor/manifests/page.json",
      "landing": "resources/editor/manifests/landing.json"
    },
    "defaultSurface": "landing"
  }
}

A single-surface application can set x-dollie-editor.manifest instead. With this configuration, info --json also includes the full runtime manifest under inventory and its path and surface under inventorySource.

npx dollie-editor catalog illustrations
npx dollie-editor catalog illustration dollie-channel-room
npx dollie-editor catalog section pg-next-features-1
npx dollie-editor catalog images
npx dollie-editor catalog sections --surface page

Plural operations return indexes; singular operations return complete fields, defaults and examples. elements/element, templates/template, image, and catalogs are also supported. Filter lists with --catalog, --category, or --kind. Use --manifest <path> to inspect an explicit manifest and --cwd to select a project. Unknown surfaces and missing manifests fail explicitly.

The SDK reads generated contracts; it does not assume how a host builds them. Wire the host's editor:catalog and editor:info scripts to regenerate the manifest before invoking the CLI. For example:

{
  "scripts": {
    "editor:catalog": "node scripts/generate-editor-manifest.mjs >&2 && dollie-editor catalog"
  }
}

Then npm run --silent editor:catalog -- illustrations returns fresh JSON. Keep generation messages on stderr. Explicit chaining also works when npm's automatic lifecycle hooks are disabled. MCP must select the same host surface; HTTP editor middleware does not select a surface for a local stdio server.

MCP/AI catalogue operations include images { category? } and image { id }. Supply the editor's image picker list through createCatalogOperations({ images }) or the manifest's optional images array. Laravel reads the same manifest array. Results include src, name, alt and category when provided. They are usable asset references, not image bytes or a filesystem scan; the host owns which assets are exposed and must serve those URLs in its preview and published site.

Continue with Author a Catalog.