recipe-authoring

Files (1)

• SKILL.md

SKILL.md (first lines)

# Recipe Authoring

A **recipe** is a TypeScript object describing one thing you want in Sitecore.
`scai provision recipe push` compiles the set to idempotent Authoring operations
and applies them. Re-running is a no-op.

## Quick start

```sh
# Validate offline — compiles the whole SET (resolves section/treelist/enum refs)
# and emits the cross-recipe aggregates (available renderings, placeholder settings)
scai provision recipe compile -n <env>

scai provision recipe diff  -n <env>            # read-only diff vs the tenant
scai provision recipe push  -n <env> --what-if  # plan, no writes
scai provision recipe push  -n <env> --allow-write
scai provision recipe roots -n <env>            # show the derived tree paths
```

Import the kind type straight from the package — defaulted fields are optional, so
you write only what you mean:

```ts
import type { ComponentTemplateRecipe } from "@sitecoreai-labs/sitecoreai-cli/recipe";
export default {
  kind: "component-template",
  schemaVersion: "1" /* … */,
} satisfies ComponentTemplateRecipe;
```

Stable kinds on `/recipe`: `ComponentTemplateRecipe`, `ContentTemplateRecipe`,
`EnumerationRecipe`, `ComponentSectionRecipe`, `DesignParametersTemplateRecipe`,
`PageTemplateRecipe`, `VariantRecipe`. Composition kinds (`PartialDesign`,
`PageDesign`, `Site`, `ContentItem`, `Dictionary`) live on `/recipe/unstable`.

## Authoring checklist

1. **One recipe per thing.** Each placeable component → one `component-template`.
   Each reusable data shape → one `content-template`. Each value list → one
   `enumeration`.
2. **Identity.** `handle: "<kebab-name>@<major>"` (e.g. `hero@1`) — load-bearing,
   seeds every GUID; never rename to change meaning, bump `@2` for a new identity.
   `name` **must match the component-map key / SDK component export** (e.g. `Hero`).
   `displayName` is the Title-Case label authors see.
3. **Props → `fields`.** Map each editable prop to a field shape (table below) and
   override with `sitecore: { type, required, hint, section, sortOrder, defaultValue }`.
   Group with `section` ("Content", "Action", "Style") and order with `sortOrder`
   (100-step increments; styles at 200+).
4. **Style / layout choices → `params`, not `fields`.** A `color`/`size`/`position`
   prop is a rendering parameter. Use `shape: "enum"` with either inline
   `values: [...]` + `sitecore: { type: "droplist" }`, or `sitecore: { enumHandle:
"<enum>@1" }` pointing at a shared `enumeration` recipe. Extract shared param sets
   into a `_params.ts` module and spread them.
5. **Repeating lists → a `content-template` + a `reference` field.** Don't hard-code
   arrays. Model the item as a `content-template`, then a `reference` (multiple)
   field with `sitecore: { source: { kind: "filter", types: ["<item>@1"] } }`
   (a Treelist). Optionally also list the handle in `insertOptions` so authors can
   create the items as children of the datasource (child-item pattern).
6. **Variants** are PascalCase and map 1:1 to React named exports (`Default`,
   `FullWidth`). The SDK looks them up case-sensitively.
7. **Containers vs leaves.** A wrapper that holds other renderings declares
   `placeholders: [{ key, allowedComponents: [...] }]` and renders
   `<Placeholder name={key} />`. A leaf lists the placeholder keys it can drop into
   in `placedIn: ["headless-main", …]`.
8. **⚠️ Every component-template MUST reference a `component-section`** via
   `section: { handle: "<section>@1" }`. Without it, the available-renderings
   aggregate skips the component and **it never appears in the Pages component
   list** — even though the rendering exists. Author one `ComponentSectionRecipe`
   per group and point every component at it.
9. **Cross-references resolve by handle** at compile time (deterministic GUIDs);
   `compile` fails `INPUT_INVALID` on an unresolved handle.
10. **Organize + verify.** Recipes must live in a **subdirectory** of the glob
    (`recipes/**/*.recipe.ts` does not match files at the glob root). Keep shared
    enums/sections/params in their own folders. Always `compile` before `push`.

## Field shapes

| Prop (React)            | `shape`                        | Default Sitecore type | Notes                                                                    |
| ----------------------- | ------------------------------ | --------------------- | ------------------------------------------------------------------------ |
| `string` heading/label  | `text`                         | Single-Line Text      |                                                                          |
| rich body / `ReactNode` | `richText`                     | Rich Text             |                                                                          |
| `imageSrc` + `imageAlt` | `image`                        | Image                 |                                                                          |
| `{ label, href }`       | `link`                         | General Link          |                                                                          |
| `boolean` flag          | `boolean`                      | Checkbox              |                                                                          |
| number                  | `number` / `integer`           | Number / Integer      |                                                                          |
| `"a" \| "b"` union      | `enum`                         | Droplink              | inline → set `sitecore.type: "droplist"`; shared → `sitecore.enumHandle` |
| list of items           | `reference` (`multiple: true`) | Treelist              | `sitecore.source: { kind: "filter", types: ["<item>@1"] }`               |

`reference` with `multiple: false` → Droplink. Override any default with
`sitecore.type`.

## Examples

**Component template** — fields + params + treelist + variants + section + placement:

```ts
import type { ComponentTemplateRecipe } from "@sitecoreai-labs/sitecoreai-cli/recipe";

export default {
  kind: "component-template",
  schemaVersion: "1",
  handle: "hero@1",
  name: "Hero", // = component-map key / React export
  displayName: "Hero",
  section: { handle: "sodra@1" }, // ← required for it to appear in Pages
  fields: [
    {
      name: "Title",
      shape: "richText",
      sitecore: { required: true, section: "Content", sortOrder: 100 },
    },
    { name: "Intro", shape: "richText", sitecore: { section: "Content", sortOrder: 200 } },
    {
      name: "Buttons",
      shape: "reference",
      multiple: true,
      sitecore: { source: { kind: "filter", types: ["nav-link@1"] } },
    },
  ],

From Sitecore-Studio-Labs/sitecoreai-cli, MIT.

More from Sitecore-Studio-Labs/sitecoreai-cli