AI Code Generation — Promoting Storybook components into XM Cloud (BYOC)

Created:
Updated:

By the time I get to this post in the series, I already have:

For anyone who has not worked with Storybook: in my projects I treat it as a local UI workbench where I can develop components in isolation, see different states, and let designers and product owners review them without touching the real site or XM Cloud.

Once that Storybook-first library is in place, I want those same components to show up as Bring Your Own Components (BYOC) inside Sitecore XM Cloud so authors can:

In this post I describe how I have approached that wiring, with AI coding agents doing the mechanical work of:

At this point in the series, the way I think about the pipeline looks like this:

Component matrix

+ requirement files

Local components

+ Storybook stories

XM Cloud BYOC

Templates + renderings + map

Next.js head

When I zoom in specifically on the BYOC wiring part, I think of it like this:

Storybook components

XM templates (SCS YAML)

Rendering items (SCS YAML)

Component map + mappers

XM Cloud Pages + Experience Edge

Storybook stays the place where I prove out UI and props, and this post is about connecting that world to XM Cloud templates, renderings, and the component map without losing the clean contracts I started with.

If you are coming from other parts of the series, this post builds directly on:

Prerequisites in the XM Cloud app repo

Everything in this post assumes you already have an XM Cloud app repo, often scaffolded via something like:

npx create-content-sdk-app@latest nextjs

and that this repo has:

I also drop an AGENTS.md into this repo, focused specifically on BYOC wiring. A trimmed-down example:

# AGENTS.md — XM Cloud BYOC wiring

## Scope
- Wire existing Storybook-first components into XM Cloud as BYOC components.
- Use requirement markdown files as the contract for fields and behavior.
- Generate SCS YAML for templates and renderings; update the component map; add data mappers.

## Preferred models
- Primary: OpenAI ChatGPT-5 Codex for code and YAML generation.
- Secondary: Claude Sonnet 4 for analysis and refactors.
- Budget: Google CLI with Gemini 2.5 (expect more manual review).

## Inputs
- Requirement files in `ai/prompts/component_specs/`.
- React components and stories in `src/components/**`.
- Existing SCS modules and example YAML under `src/items`.

## Outputs
- New/updated YAML for templates and renderings under `src/items`.
- Updated component map file mapping renderings to React components.
- Data mapper modules that transform Content SDK/GraphQL output into component props.

This gives coding agents just enough context to stay in their lane.

From requirement files to XM Cloud templates (YAML)

XM Cloud uses Sitecore Content Serialization (SCS) to version templates, renderings, and other items as YAML in your repo. My pattern has been:

It is worth calling out that there is also a Sitecore MCP server option that lets a coding agent talk directly to a running Sitecore instance and create or modify items through the API. On some projects that can be very powerful. In this particular setup, though, I chose to work directly against a remote XM Cloud instance instead of giving every developer a full local Docker environment. For that reason I have leaned on YAML-serialized files + Sitecore CLI pushes as my main promotion path: agents generate SCS YAML in the repo, I review it, and then I use the CLI to push changes up to XM Cloud. In practice that has been simpler to roll out across the team and more reliable for me than trying to keep local containers and MCP sessions healthy on every laptop.

Where template YAML lives

The exact structure depends on your starter, but a common pattern for templates is:

For example:

Your sitecore.json file references these paths via modules; I usually point AI at that file so it does not invent new folders.

A minimal template YAML shape

I do not expect AI to be perfect with Sitecore IDs, but it can generate a solid starting point. A highly simplified example for an Accordion component might look like:

---
ID: "{TODO-GENERATE-GUID}"
Parent: "{PARENT-TEMPLATES-FOLDER-GUID}"
Template: "{TEMPLATE-TEMPLATE-GUID}"
Path: /sitecore/templates/Project/Cws/Components/Accordion
SharedFields:
- ID: "{BASE-TEMPLATE-FIELD-GUID}"
  Hint: __Base template
  Value: "{BASE-COMPONENT-TEMPLATE-GUID}"
Languages:
- Language: en
  Versions:
  - Version: 1
    Fields:
    - ID: "{TITLE-FIELD-GUID}"
      Hint: Title
      Value: "Single-Line Text"
    - ID: "{SUBTITLE-FIELD-GUID}"
      Hint: Subtitle
      Value: "Single-Line Text"
    # ...

In real projects, I pull actual IDs from existing items or let Sitecore CLI create them, but AI is still helpful at:

Batch prompt: generate template YAML from requirements

Here is the kind of batch prompt I use to get AI to propose template YAML for all components:

# Template YAML generation from requirements

You are working in an XM Cloud app repo that uses Sitecore Content Serialization (SCS).

Goal:
- For every component requirement file in `ai/prompts/component_specs/`, propose a corresponding template YAML file under `src/items/templates/Project/<ProjectName>/Components/`.

Preferred models:
- OpenAI ChatGPT-5 Codex (primary).
- Claude Sonnet 4 (fallback).
- Google CLI with Gemini 2.5 only if needed and with extra review.

Inputs:
- Requirement markdown files (one per component).
- Example template YAML files already present under `src/items/templates/Project/<ProjectName>/`.
- `sitecore.json` to understand module paths and serialization roots.

For each component:
- Extract the Name and Fields from the requirement file.
- Propose a template name under `/sitecore/templates/Project/<ProjectName>/Components/<ComponentName>`.
- List fields with suggested Sitecore field types (Single-Line Text, Rich Text, Image, General Link, Checkbox, Droplist, Multilist, Treelist, etc.).
- Output a YAML file that follows the structure of existing templates.

Important:
- Use placeholder IDs like `{TODO-GUID}` where you cannot infer real IDs; do not invent random GUIDs.
- Keep one template per component, unless the requirements explicitly call for separate datasource vs page templates.

After an initial batch, I usually copy AI’s YAML into the repo, then let Sitecore CLI or the XM Cloud environment generate actual IDs when I create or sync items.

Rendering items and datasource locations

Templates define the data shape; rendering items define how those templates show up as components in XM Cloud.

Where rendering YAML lives

Again, paths vary, but a common pattern is:

For example:

These rendering items usually reference:

Prompt: generate rendering YAML from templates + requirements

Once templates exist (even in draft form), I give AI a second task:

# Rendering YAML generation from templates

You are continuing the XM Cloud BYOC wiring.

Goal:
- For every component template under `src/items/templates/Project/<ProjectName>/Components/`, generate a corresponding rendering item YAML under `src/items/renderings/Project/<ProjectName>/Components/`.

Inputs:
- Template YAML files for each component.
- Requirement markdown files (to understand behavior, datasource usage, and notes).
- Example rendering YAML files already present in `src/items/renderings/...`.

For each component:
- Choose a rendering name (e.g., `Accordion`, `IndustryCard`) consistent with the project’s naming conventions.
- Reference the appropriate datasource template(s) from the template YAML.
- Configure allowed placeholders and datasource locations if the project has conventions for these.

Output:
- One rendering YAML file per component under `src/items/renderings/Project/<ProjectName>/Components/`.

Constraints:
- Follow existing rendering YAML structure in the repo.
- Use placeholder IDs when you cannot infer real ones; avoid inventing random GUIDs.

These rendering items are what XM Cloud Pages will use when authors add components to pages.

Updating the XM Cloud component map

With templates and renderings in place, XM Cloud still needs to know which React component renders each rendering definition. That is where the component map comes in.

The exact shape of the component map depends on your scaffold, but it is typically a TypeScript file that exports a mapping from rendering identifiers to React components under src/components.

Typical component map shape

In an App Router + Content SDK project, I commonly see something along the lines of:

// Example, actual paths and names vary by scaffold
import { ComponentMap } from '@sitecore/content-sdk-react';
import { Accordion } from '@/components/Accordion/Accordion';
import { IndustryCard } from '@/components/IndustryCard/IndustryCard';

export const componentMap: ComponentMap = {
  Accordion,
  IndustryCard,
  // ...
};

Sometimes the key is a rendering ID or a component name defined in YAML; either way, I keep the naming aligned with the rendering items AI just generated.

Prompt: generate or update component map entries

Here is a prompt pattern I use to let AI update the component map based on existing components and requirement files:

# Component map update from requirements and components

You are working in an XM Cloud Next.js app with Content SDK.

Goal:
- Ensure the component map file correctly maps all BYOC rendering names to their React components in `src/components`.

Inputs:
- Requirement files in `ai/prompts/component_specs/`.
- React components under `src/components/**`.
- Rendering YAML under `src/items/renderings/Project/<ProjectName>/Components/`.
- Existing component map file (for example `.sitecore/component-map.ts` or `src/lib/componentMap.ts`).

For each requirement file:
- Determine the component name (using the `## Name` section and filename).
- Locate the corresponding React component folder under `src/components/<ComponentName>/`.
- Determine the rendering name from the rendering YAML (usually the item name or a field like `RenderingName`).
- Add or update an entry in the component map so that the rendering name resolves to the React component.

Constraints:
- Preserve existing imports and mappings not related to these components.
- Keep naming consistent with the project conventions.
- Do not introduce new frameworks or change the Content SDK configuration.

After AI proposes changes, I review the diff and run type checking before committing.

Content SDK data mappers: keeping props clean

The last wiring step is data: making sure the Content SDK provides data in the shape my components expect.

Route data and Content SDK

In XM Cloud, the Content SDK typically:

Rather than letting raw CMS data leak into props, I generate mappers that transform Content SDK/GraphQL shapes into view models aligned with my requirement files.

Prompt: generate mappers from requirements + components

Here is a mapper-focused prompt that ties Content SDK output to component props:

# Data mapper generation from requirements and Content SDK models

You are working in an XM Cloud Next.js app using the Sitecore Content SDK.

Goal:
- For each component, create a mapping function that converts Content SDK (or Experience Edge GraphQL) data into strongly typed props that match the requirement file and React component.

Inputs:
- Requirement markdown files under `ai/prompts/component_specs/`.
- React components and their props under `src/components/**`.
- Existing Content SDK models and route loaders (e.g., `src/lib/sitecore/contentSdk.ts`, route handlers under `src/app/**`).
- Example layout/GraphQL responses captured as JSON for a few sample pages.

For each component:
- Define a TypeScript `ViewModel` interface that mirrors the props expected by the component.
- Implement a mapper function `map<ComponentName>Data` that:
  - accepts the relevant slice of Content SDK / GraphQL data (e.g., a rendering’s fields node),
  - safely handles null or missing fields,
  - and returns a populated `ViewModel`.
- Place mapper files under `src/mappers/<ComponentName>.ts`.

Constraints:
- Do not call the Content SDK directly from components; mappers are used by route loaders or composition layers.
- Keep field names aligned with Sitecore field names where feasible.

I then have route loaders or composition helpers call these mappers as they build the props passed into the component map.

Pushing YAML to XM Cloud via CLI

Once templates and renderings are serialized and the component map and mappers are in place, it is time to push the YAML to an XM Cloud environment.

The exact commands depend on your setup, but the usual flow with Sitecore CLI looks like:

  1. Install and configure the CLI (once per machine), for example:
    • dotnet tool install --global sitecore.cli
    • dotnet sitecore login (against your XM Cloud environment).
  2. From the directory that contains sitecore.json, run:
    • dotnet sitecore ser push to push serialized items (templates, renderings, etc.) to XM Cloud.
  3. Publish updated items (via XM Cloud UI or deployment pipeline) so they become available to Experience Edge.

In many XM Cloud setups, serialization push is wired into the XM Cloud Deploy pipeline, so committing YAML to your main branch and triggering a deploy will push items for you. I still like having the CLI handy for local validation and dry runs.

I also ask AI to generate a short “BYOC deployment checklist” in the repo docs so teammates know which commands to run and in what order.

A combined BYOC promotion task for agents

Putting this together, here is a higher-level prompt I have used to orchestrate the whole BYOC promotion step with an agent:

# BYOC promotion from Storybook components to XM Cloud

You are an AI coding agent helping wire a Storybook-first Next.js component library into Sitecore XM Cloud as BYOC components.

The previous steps have produced:
- Requirement markdown files in `ai/prompts/component_specs/`.
- React components and stories in `src/components/**`.
- An XM Cloud app with Content SDK, SCS YAML under `src/items`, and a component map file.

Your tasks:
1. For every requirement file, propose or update:
   - Template YAML under `src/items/templates/Project/<ProjectName>/Components/`.
   - Rendering YAML under `src/items/renderings/Project/<ProjectName>/Components/`.
2. Update the component map so each rendering name resolves to the correct React component.
3. Generate or update data mapper modules under `src/mappers/` to convert Content SDK data into component props.
4. Produce a short markdown summary (`ai/prompts/byoc_promotion_log.md`) listing:
   - Components wired,
   - Files touched (templates, renderings, mappers, component map),
   - Any TODOs or assumptions that need human review.

Constraints:
- Follow project conventions from `AGENTS.md`.
- Do not introduce new dependencies or frameworks.
- Use placeholder IDs in YAML where real IDs are unknown; humans will adjust them.
- Do not modify CI or deployment configuration.

This gives me a repeatable pattern I can run whenever new components appear or existing ones change.

How the series fits together now

With this post in place, the AI Code Generation series reads as one coherent narrative:

Taken together, they describe a pipeline where:

Additional resources

Previous Post
AI Code Generation — Local-first component library with Storybook
Next Post
Integrations — Reviewing XM Cloud / Next.jspull requests with coding agents safely