
sitecore-content-sdk
Router-agnostic Content SDK essentials plus the Sitecore side of a component: troubleshooting hub, feature planner, component review, create a rendering, list and navigation components, collection data models, icons, layout composition, field usage, resolvers, personalization, search, consent, upgrades. Install with a router plugin.
- version
- 0.20.1
- GitHub stars
- 12
Install
/plugin install sitecore-content-sdk@sitecore-skills-pocsRun it inside Claude Code after adding the marketplace with /plugin marketplace add Chris1415/sitecore-skills-pocs.
Contents
Discovered from sourceSkills 23
Content SDK analytics events
The Content SDK sends visitor events to SitecoreAI by calling POST {edgeUrl}/v1/events/v1.2/events?siteId=<site> with the x-sitecore-contextid header. One core singleton (initContentSdk) holds two plugins. analyticsPlugin owns the visitor id: it calls create.json and stores the result in the sc_cid cookie. eventsPlugin owns the five send functions. Every event function reads that singleton at call time, and that one fact explains most of the limits below.
When to use
- Adding a custom event, a page view, an identity call or a form event to a head app.
- An event "does not show up", Performance → Events is empty, or you need to prove that a beacon fired.
- Deciding whether an event goes from the browser or from the server.
- Reviewing
src/Bootstrap.tsx,src/components/content-sdk/CdpPageView.tsxor any call into@sitecore-content-sdk/events.
When NOT to use
- Consent. Use
content-sdk-tracking-consent. That skill owns the banner wiring, the gates, withdrawal and the cookie categories. This skill assumes the gate exists and never bypasses it. - The personalization decision (PersonalizeProxy, variant ids,
_variantId_rewrites). Usecontent-sdk-personalization. - Creating flows, audiences or A/B tests in SitecoreAI. Use
sitecoreai-personalization.
Rule zero: every tracking call sits behind the consent gate
The SDK has no consent API. A call you add here is consent-safe only if it can run when the visitor has consented and cannot run when they have not. In practice, every helper in this skill goes through the gate that content-sdk-tracking-consent defines. That covers Bootstrap's init, CdpPageView, your custom helpers, <Form> and PersonalizeProxy.skip. Do not add a second, local consent check, and do not call initContentSdk from anywhere except the place that skill defines.
1. Initialization: what the scaffold ships
| Piece | Where (App Router) | What it does |
|---|---|---|
Bootstrap (client) | src/app/[site]/layout.tsx, first child before {children} | initContentSdk({config:{contextId: clientContextId, edgeUrl, siteName}, plugins:[analyticsPlugin({options:{enableCookie:true, cookieDomain: hostname without www.}, adapter: analyticsBrowserAdapter()}), eventsPlugin()]}). Skips NODE_ENV=development and draftMode |
CdpPageView (client) | rendered by Layout through Scripts | pageView({channel, currency, page, pageVariantId, language}) once per route, only when mode.isNormal |
BotTrackingProxy | src/proxy.ts, second, after preview | Bot UA → sc_bot=1 cookie plus a server botPageView in waitUntil |
- Plugin order matters. Plugins initialize in array order, and a missing dependency throws IE-001. Keep
analyticsPluginbeforeeventsPlugin. - Context ids. The browser uses
config.api.edge.clientContextId, which defaults toNEXT_PUBLIC_SITECORE_EDGE_CONTEXT_IDand is inlined into the public bundle. The server usesconfig.api.edge.contextId(SITECORE_EDGE_CONTEXT_ID).defineConfighas no analytics or events keys; everything is set through plugin options. - A 201 does not prove which context you are on. A preview context id also gets 201. Read the live value from
window.scContentSDK.analytics_core.options.contextIdand compare it with the context you expect. - Ordering holds by tree position only. Bootstrap's effect commits before the page's effects because Bootstrap renders first. Anything that delays or skips that init (a conditional render, a Suspense boundary, consent granted later) makes every later event reject with
[IE-002] SDK not initialized, and the scaffold's.catch(console.debug)swallows it. Bootstrap's effect depends only on[siteName, isPreviewMode], so it does not re-run on soft navigation. The cache-components template wraps Bootstrap in<Suspense>; whether the ordering still holds there is [probe-gated: P6, cache-components leg not yet run]. - Pages Router delta. Bootstrap mounts in
src/pages/_app.tsx, and the proxy chain has noLocaleProxy. Otherwise the same rules apply.
2. Pick the event
| Event | API (@sitecore-content-sdk/events) | Wire type | Send from | Use it for |
|---|---|---|---|---|
| Page view | pageView(data?: PageViewData) | VIEW (the dashboard shows it as "pageView") | Client, through the scaffold's CdpPageView only | Every normal page render. pageVariantId ties the view to a personalization or A/B variant |
| Custom | event(data: EventData) | your type string | Client by default | Interactions and conversions |
| Form | form(formId, 'VIEWED' | 'SUBMITTED', componentInstanceId) | FORM | Client, automatic through the SDK <Form> component | Sitecore Forms. Never hand-wire it |
| Identity | identity(data: IdentityData) | IDENTITY | Client today. Server-side is [probe-gated: P14] | Login or a known-visitor form submit. It is the input to identity resolution, which is off until an org identity rule exists |
| Bot view | botPageView({page, language, userAgent}) | VIEW, channel:'bot' | Server, inside BotTrackingProxy only | Crawler traffic. Never call it yourself |
Field limits are enforced client-side, and a violation throws (the promise rejects) rather than being swallowed:
extensionData: at most 50 attributes after flattening (IV-006). It applies topageView,eventandidentity.identity:identifiers: [{id, provider}]is required (MV-003).dobis date-onlyYYYY-MM-DD(IV-003) from events 2.1.2 on.identifier.expiryDatemust be a full ISO date-time (IV-005).emailis validated (IV-004). Thebeta.atomsbuilds predate 2.1.2 and reject a date-onlydob.pageViewreads the referrer only on the first view per page load (static isFirstPageView).includeUTMParametersdefaults totrue.- Set
currencyfrom the site's real currency. The scaffold hard-codes'USD'.
Minimal calls, with full typed signatures in references/api-surface.md:
await event({ type: 'ACME_NEWSLETTER_SIGNUP', channel: 'WEB', page: route.name, language, extensionData: { list: 'weekly' } });
await identity({ identifiers: [{ id: crmId, provider: 'acme-crm' }], email, dob: '1990-04-15', channel: 'WEB' });
// pageView and form: leave them to CdpPageView and <Form>
3. The client-side custom event helper (the default path)
Put one helper in src/lib/tracking.ts and make every component call it. Never call event() directly from a component.
'use client';
import { event, type EventData } from '@sitecore-content-sdk/events';
import { getClientId } from '@sitecore-content-sdk/analytics-core';
const SITE_PREFIX = 'ACME'; // one per site; see § 5
export async function track(action: string, extensionData?: EventData['extensionData'], page?: string) {
try {
getClientId(); // throws IE-002 when Bootstrap did not init: dev, editing/preview, no consent
} catch {
return null;
}
if (document.cookie.split('; ').some((c) => c.startsWith('sc_bot='))) return null; // event() does not skip bots
return event({
type: `${SITE_PREFIX}_${action}`,
channel: 'WEB',
page,
language: document.documentElement.lang || undefined,
extensionData,
}).catch((e) => { console.debug('[track]', e); return null; }); // validation errors reject
}
Why each guard exists:
- IE-002 guard. If init never ran,
event()rejects. ThegetClientId()probe turns "no init" (dev, draftMode, no consent) into a silent no-op, so the helper inherits the suppression that Bootstrap and the consent gate already apply. - Bot guard.
pageViewskips bots, butevent()andidentity()do not. A bot has nosc_cid, so the event goes out withbrowser_id: ""and is rejected (404 or 400 observed), swallowed asnull.sc_botis set server-side and is readable from JS. - Editing. Bootstrap does not init in draftMode, so the IE-002 guard covers Pages editing and preview. In a component, also check
useSitecore().page.mode.isNormalbefore calling, asCdpPageViewdoes. - Exit clicks.
sendEventusesfetchwith nokeepalive, so an event fired on a click that navigates to another site is lost: measured 2026-10-05 on a production build (real Chrome UA), the POST stayedpendingwhen the cross-origin navigation replaced the page. A same-origin hard navigation (a plain<a>to the same site) is safe: the event and the next page's VIEW both returned 201. For outbound links either accept the undercount and document it, delay-then-navigate (awaittrackEventwith a ~300 ms timeout, thenlocation.assign), or queue via@sitecore-content-sdk/events/browserand flush on the visitor's next page (only if they return). A redirecting form submit is unmeasured [probe-gated: P16]. - The
./browserqueue.addToEventQueue/processEventQueuefrom@sitecore-content-sdk/events/browserbatch events in sessionStorage across navigations. They still await init, so they are not a way to buffer events before init. - BYOC. The scaffold's
src/byoc/index.tsxpasses the whole events module to BYOC components (FEAAS.setContextProperties({ eventsSDK: Events })). A BYOC component'seventsSDK.event(...)uses the same singleton and the same rules. Route it through the same naming convention, and make the BYOC author aware of the consent gate.
4. Server-side events: only with the carrier pattern, and not under concurrency
Decision rule: send from the client by default. Use a server event only when the action exists only on the server (a webhook or a server-validated conversion), and only if all of the following hold:
- It runs in a Route Handler, with the carrier pattern. Give
analyticsProxyAdapter(req, carrier)anew NextResponse(null)as the carrier, then copycarrier.cookies.getAll()onto the response you return.return NextResponse.next()from a Route Handler is HTTP 500 ("not supported"). Without the cookie copy, a fresh visitor'ssc_cidis lost. RSC cannot set cookies at all. The full code is inreferences/server-events.md. - Pass
page,languageandreferrerexplicitly. Server-side they default to an empty string or null. - Bot UAs fail silently. The adapter skips
create.jsonfor bots, so the event goes out withbrowser_id: "", gets a 400, andevent()resolvesnullwithout throwing. - No concurrency. This is a live limitation (T15).
initContentSdkoverwrites a process-global singleton, andevent()reads it at call time. In a measured run, 50 parallel requests with 0–200 ms jitter sent 49 of 50 events under another visitor'sbrowser_id, and edge-platform answered 201 to all 50. Without jitter it was 24 of 50.Set-Cookiestayed correct per request, so nothing in the response reveals the mis-attribution. Until Sitecore fixes the singleton, a per-requestinitContentSdkon the server is safe only when calls are serialized per process. The escape hatch is a direct POST with the request's ownsc_cidand no SDK state (references/server-events.md). The same singleton runs insidePersonalizeProxyandBotTrackingProxy; whether the proxy path cross-contaminates is [probe-gated: P22]. - Geo. A server event comes from the server's IP. Whether the endpoint accepts a geo or IP override is [probe-gated: P12].
Pages Router: analyticsServerAdapter(req, res) takes Node IncomingMessage / OutgoingMessage and has the same singleton problem. Its API-route behaviour has not been probed. Treat it as [probe-gated: not yet in the probe plan].
5. Name custom events: the endpoint validates nothing
The ingress accepts any type string with 201. That includes typos, lowercase strings and the legacy reserved SC_ prefix. The Performance → Events dashboard lists custom events by their exact type, next to pageView. Naming discipline is therefore the only control.
- Prefix with the site:
<SITE>_<OBJECT>_<ACTION>, upper snake case, for exampleACME_NEWSLETTER_SIGNUPorACME_PDP_ADD_TO_CART. The SDK's own JSDoc suggestssite:ACTION. Pick one form per estate and never mix them. - Never reuse reserved or standard names:
VIEW,IDENTITY,FORM, the legacy CDP namesADD,SEARCH,TRACKING,INTERACTION, anything startingSC_(SC_SEARCH_WIDGET_VIEW/_CLICKbelong to Sitecore Search), and the display labelpageView. Ingress does not reject them. How the dashboard and Profiles treat them downstream is [probe-gated: P10]. - Integrated search has its own event:
type: 'search'withcore: { componentId, componentInstanceId, interactionType, keyword, nullResults }feeds the search dashboard (content-sdk-search). It is distinct from standalone Search'sSC_SEARCH_WIDGET_*and from the reserved uppercase legacySEARCH. Case sensitivity [probe-gated: P7]. - Keep
typestable. The dashboard groups by the string, so a rename starts a new row. Put variable data inextensionData, never intype. - Tag synthetic traffic. Probes and tests use a
<SITE>_PROBE_*type orextensionData.probe_tag, so they can be filtered out of live dashboards.
6. Suppression: who sends nothing, and why
| Context | Bootstrap init | CdpPageView | Custom helper (§ 3) | <Form> | BotTrackingProxy |
|---|---|---|---|---|---|
next dev | off | off | no-op (IE-002) | fires, unhandled IE-002 [probe-gated: P16] | off |
| Pages editing / preview (draftMode) | off | off (!mode.isNormal) | no-op | off in editing | skips preview |
Bot UA (isbot) | inits, but no sc_cid | skipped ("visitor is a bot") | no-op (sc_bot) | skipped | sets sc_bot, sends botPageView |
Headless browser (Playwright default, HeadlessChrome, curl) | treated as a bot | skipped | no-op | skipped | sc_bot (not on localhost) |
localhost production build | on | on | on | on | skipped, unless SITECORE_ENABLE_BOT_TRACKING=true |
| No consent | off (via the consent skill) | off | no-op | see the consent skill | unaffected (sets only sc_bot) |
The editing host is a production build. Whether it leaks events on direct, non-preview hits is [probe-gated: P21].
7. Verify that an event really fired
Errors are swallowed, and there is no timeout. sendEvent catches every transport failure and resolves null, so a console with no output proves nothing.
- Use a production build against the LIVE context (
next build && next start, or the deployment). Dev and preview send nothing. - Pin a real Chrome UA in any automated browser, for example
…Chrome/141.0.0.0 Safari/537.36. A default headless UA is a bot, and every "0 events" assertion run with one passes even when tracking is broken. - Assert the positive control first:
GET …/browser/create.jsonreturns 201 andsc_cidis set. Only then trust a count. - Assert the beacon:
POST …/v1/events/v1.2/eventsreturns 201{"status":"OK","ref":…}, and the request bodytypeis your name. - Read a failure from its body. A 404 is either
No sitecore context(wrong or missing context id) orInvalid browser id/ref specified(missing or unknownsc_cid).siteIdis not validated: a bogus site also gets 201, so it is not a negative control. Use a bogus context id instead. - Check the server side. Run with
DEBUG=content-sdk:events(or the fetch tap inreferences/testing.md); the events log includes the response status. - Check ingestion. In SitecoreAI, open Performance → Events. Custom events are listed by
type, with event and session counts, next topageView. Ingestion latency, and whether IDENTITY and FORM show up there and in Profiles, are [probe-gated: P10]. - Check the site has an analytics identifier for the language you track. A 201 proves the call was accepted, not that it is attributed (step 5:
siteIdis not validated). Sitecore's site analytics need one identifier per site language, and a site created by serialization push or a newly added language has none (sitecoreai-sites§ Pitfalls). Whether events sent without one are kept, dropped, or attributed later is [probe-gated].
Recipes, Playwright code and controls: references/testing.md. Wire shapes and the 404/400 table: references/wire-format.md.
Hard rules
- Every call goes through the consent gate in
content-sdk-tracking-consent. Never add an ungatedinitContentSdkor a directevent()call. - Send from the client by default. Server events use the carrier pattern, never
NextResponse.next(), and are never concurrent until T15 is fixed. - Leave page views to
CdpPageView, form events to<Form>and bot views toBotTrackingProxy. Do not double-send them. - Validate locally what the SDK validates: 50
extattributes,identifierspresent, date-onlydob. - Never treat console silence, a rendered page or a headless "zero" as proof. Proof is a 201 on the wire, plus the dashboard row.
Stop conditions
- Stop if a change would initialize the SDK, set
sc_cidor send any event without going through the consent gate. - Stop if asked to send server-side events from a concurrent context (Route Handler under load, RSC, proxy) without serialization or the direct-POST escape hatch. Cite T15.
- Stop if
identity()would carry restricted data (health, payment, government ids). SitecoreAI forbids it, and deletion needs a support case. - Stop if an e2e check of tracking runs with a headless UA and no positive control.
References
references/api-surface.md: exports, typed signatures,.d.tspaths, error codes.references/wire-format.md:create.json, the events request and response, the 404/400 classes, the cookies tracking sets.references/server-events.md: the carrier-pattern Route Handler, the direct-POST escape hatch, the T15 evidence.references/testing.md: Playwright UA pinning, network assertions, controls, the concurrency check.- Related skills:
content-sdk-tracking-consent,content-sdk-personalization,content-sdk-app-router-multisite-management(proxy chain order). - Content SDK 2.0: tracking, events and personalization.
Atomic Design assessment for an existing head app
Answers one customer question: which of our components would be better as atoms + composed Documents, and what would moving them cost? The output is a report with a verdict per component, a proposed atom set and a migration plan. Nothing is changed.
0. Frame it honestly first
Say these before any scan, because they decide whether the assessment is worth doing:
- Atoms are beta (
beta.atomsdist-tag only, exact pins, React only). Checkcontent-sdk-app-router-atoms§ 1 for the current stamp. - The payoff is marketer autonomy: new section layouts composed in Design Studio without a deploy. A team that ships few new section types gains little.
- Design Studio low-code access on the customer's tenant is
[UNVERIFIED](gating unknown). Without it a Document can be rendered only from a mock MMS: no way to write one to a tenant is known, so there is nothing to migrate to. - Page structure stays code. Placeholders, splitters, containers, partial designs, navigation, search, forms and personalization are not atom territory.
1. Scan
node scripts/scan-atomic-candidates.mjs --app <head-app-dir> --md > atomic-scan.md
node scripts/scan-atomic-candidates.mjs --app <head-app-dir> --json atomic-scan.json
It reads src/components/**, honours the app's componentMap.exclude, follows local imports one level, and prints per file: verdict, leaf primitives used, variants, fields and the reasons (signal + line). Then it prints the atom inventory ranked by coverage and what Content Kit lacks.
| Verdict | Meaning | Typical members |
|---|---|---|
low-code-candidate | Only authored fields + static markup + param/variant styling | Content block, rich text, promo without logic, simple CTA, quote, stat |
partial | Composable core with something a Document cannot do: a list over datasource children, route-context fields, structured data, editing-only branches, size | Card lists, title with route fallback, promo with JSON-LD |
keep-code | Data fetching, client state, event handlers, forms, placeholders, personalization | Navigation, search, forms, splitters, containers, header/footer |
It is a triage aid, not a decision. Measured blind spots (2026-10-29): regex not a TS parse; logic two imports deep is invisible; a shared helper with useState taints every importer (Sitecore's starter Icon.tsx turned every icon button into keep-code); conditional wrapping (link around an image only outside editing) is not seen; variant files (Hero.Split.tsx) count as separate components.
2. Read every non-keep-code verdict
For each low-code-candidate and partial, open the source and answer:
- Leaves. Is every authored value a Text / RichText / Image / Link / Date field? Anything else (number display, checkbox-driven logic, multilist) needs a custom atom or stays code.
- Lists. Does it render datasource children or a multilist? Treat as
partial: whether a Document can iterate a list is[UNVERIFIED]. Plan a code container whose items are low-code, or keep it. - Variants. How many presentations exist (
FieldNames/ named exports / variant files)? Many presentations over the same fields is the strongest signal FOR atoms: each becomes a Document, not a code variant. - Editing behaviour. Does it branch on
page.mode.isEditingto show empty-field placeholders? A Document cannot. Inline editing inside atoms is[UNVERIFIED], so a component whose authors rely on inline editing pays a real authoring cost. - Dictionary / i18n labels. Fixed microcopy from the Sitecore Dictionary or
next-intlhas no binding in a Document. Move it to a field or keep code. - Change frequency. How often does marketing ask for a new look of this? Low demand → low value, whatever the verdict.
Upgrade or downgrade the scanner's verdict and record why. Measured spread: a carefully authored production app (15 components) came out 0 / 12 / 3, because every component carries editing branches and dictionary labels; Sitecore's article starter 14 / 7 / 77.
3. Derive the atom set
From the confirmed candidates, decompose each into elements and collect:
- Leaf atoms = the primitives in the scan's inventory (Heading, Paragraph, Image, Button/Link usually cover 70–80%). Start from Content Kit's leaf atoms and add only what the inventory demands (Date, Quote, Icon, Badge, List item).
- Container atoms = recurring wrappers (
flex/grid/ card shells). Content Kit'sContaineris a generic flex wrapper with free CSS values; a governed token Stack comes first when composers should only pick from a scale, Grid second. - Tokens, not classes. Every repeated design decision in the existing components (spacing steps, tones, heading sizes, radii) becomes an enum prop on an atom. If the existing code uses arbitrary values, that inconsistency surfaces here; resolve it with the design owner before writing atoms.
- Target 8–15 atoms. More means the atoms have become components; fewer means composers fall back to
className.
Write each atom with content-sdk-app-router-atom-create.
4. Plan the migration (side-by-side, never in place)
Per candidate component:
- Keep the datasource template and its field names. A Document binds
{"$state": "/fields/<Name>"}, so existing datasource items render unchanged once the field names match. That is the cheapest path and avoids a content migration. - New rendering, same datasource. Create a rendering on the CM's Hosted JSON Rendering template with its
ComponentRefpointing at the Document path; keep the old code rendering available. - Compose the Document in Design Studio (by hand only against a mock MMS) reproducing the current look; variants become further Documents (
<default>|<Variant>refs). - Swap per page, compare visually against the code version, then retire the code rendering when no page uses it.
Order the work in waves:
- Wave 0, probe (mandatory). First gate: does Design Studio open
library-low-codeon this tenant? Read the editing host's runtime log for the mode. On one test environment on 2026-11-03 (stamp20261021204512, six atoms, lock passing, site bound to a running editing host) the editing host's log showed 30 Design Library sessions, all modelibrary, nonelibrary-low-code, and a Design Studio draft component opened with noComponentRef, so it rendered as an unknown component. If it does not, stop here. Then one simple candidate end to end on a non-production tenant: Document storage, ComponentRef delivery on preview and live, runtime CSS on the real host, editor experience. Most[UNVERIFIED]items in the atoms skill resolve here or kill the plan. - Wave 1. Atoms + the highest-variant candidates.
- Wave 2.
partialcomponents as hybrids (code container, low-code items). - Never.
keep-code.
5. Report
Write atomic-design-assessment.md with:
- Context: app, SDK version, router, component count, the § 0 framing and whether Design Studio low-code is available.
- Verdict table: component, scanner verdict, final verdict, reason, variants, monthly change demand (if known).
- Proposed atom set: atom, kind (leaf / container), props (fields + enums), covers which components, Content Kit or custom.
- Token decisions the atoms freeze (spacing, tone, type scale), with open questions for the design owner.
- Migration waves, with Wave 0's probe questions explicit.
- Costs and risks: beta pins on the whole app, authoring changes (inline editing, empty-field placeholders), CI lock gate, runtime CSS on the host, the cache-components incompatibility, team skills (atoms are code; composition becomes a content task needing governance).
- Recommendation: go / pilot / not now, in one paragraph.
6. Stop conditions
- The app is Pages Router, cache-components, Angular or .NET: report it. Atoms there are unstyled, return 500, or do not exist.
- Fewer than ~5 confirmed candidates: recommend not now. The fixed cost (beta upgrade, CI, governance) needs volume.
- The customer cannot get Design Studio low-code on a tenant: recommend pilot only after access is confirmed.
Collection data models
A component that shows many items is not one problem. The question that decides everything is who authors the rows, and where. Answer it before choosing a template, a query or a resolver.
The four classes
| Class | Who authors the rows, where | Examples | Shape | Delivery | Editable in Pages |
|---|---|---|---|---|---|
| A. Owned rows | The author of this component, here | tabs, accordion panels, stats, a hand-made card row | Container datasource with row children | Rendering ComponentQuery, every field as jsonValue | Yes: row fields inline and reorder (confirmed in Pages 2026-11-04); add and delete through Manage items |
| B. Derived view | Someone else, on other pages | latest news, child-page lists, sibling menus | No datasource rows; the source pages | Server-side Edge fetch, cached, revalidated on publish | No, by design: an "edit at source" link in editing mode |
| C. Curated reference | This author picks; the items live elsewhere | featured products, shared slides | Multilist / Treelist field on the datasource | The field itself (items arrive in layout data) | Picking and ordering yes; the picked items' fields are edited at their source |
| D. Shared library | A team, in one folder, used by many components | client logos, team members, 100+ items | Folder with insert options, no rows in layout data | Ids first, then fetch the subset shown | Through Manage items on the folder, not inline |
Tie-breakers:
- Rows that exist only for this one placement are A. Rows that are pages in their own right are B.
- More rows than the query budget allows (a
ComponentQueryholds about 14 to 21 rows by field count; a server fetch withurlabout 10 to 12 per request) cannot be A: choose C (curate a few) or D. - "Show N random" or "newest N" is a selection over a set, so the set is B or D, never A.
Delivery, ranked
ComponentQueryon the rendering withjsonValuefields (class A). It returns the container fields and the children in one payload;jsonValuekeeps them editable. It replaces the wholefieldspayload, so select everything the component renders. Clear the rendering's resolver: a resolver set alongside a query won in our projects [measured, not documented].- Server-side Edge fetch (classes B and D) through the SDK client (
client.getData) in a server component. It pages freely (cursor, variablefirst), has no republish dependency and needs caching plus revalidation. No editing metadata, so it is only for rows authored elsewhere. - Multilist / Treelist field (class C). The picked items arrive whole in layout data, so cost grows with their fields.
- Content resolvers: avoid. Sitecore documents that content resolvers are not supported with Edge runtime publishing, custom resolvers are unsupported in SitecoreAI, the children resolvers have no filtering or paging and drop the container's own fields, and nothing documents their output as editable.
Mechanism details, the measured budget and the republish rule: references/mechanisms.md.
Rules that decide the outcome
- The budget is per request. Edge prices
urland every named field per child. AComponentQueryrow pastchildren(first: N)is dropped without an error; a query over budget arrives asisContentResolved: false. Sizefirstabove the authored row count and record that maximum next to the query; the probe sees only delivered < total, so it cannot enforce this headroom. - Freshness differs by delivery. A row added to a resolver or
ComponentQuerylist reaches the page only after the page is republished. A server fetch sees it after the item is published and the cache revalidates. - Never the whole library in layout data. For class D, page the cheap
id nameselection, choose the ids (sample, newest, tag), then fetch only those items' fields. - Filters live on the container. A tag filter is a Multilist of tags on the datasource (class A) or a parameter of the fetch (B, D); filter in code. A legacy "tag folder" read by id becomes that field.
- Order is authored. Seed rows with
__Sortorderin steps of 100; Edge returns children in sort order, alphabetical without it [measured 2026-09-27]. - Derived views show the way to their source. In editing mode render an "Edit source" link per row (the item's page), so authors are never stuck on content they cannot change here.
Migrating a legacy list
Most XSLT, WebForms and MVC lists walked the content tree. Translate each by who authors the rows: references/legacy-translation.md (./item loops, sc:item(id) reads, child folders of a page, tag-filtered galleries, "N random").
Verification
- Run
scripts/probe-list-delivery.mjs --context <id> --site <site> --route <path>on every route with lists. It classifies each placement's payload, compares delivered rows with the datasource'schildren.total(silent drop), flags rows not selected asjsonValueand any resolver payload, and reports a datasource with children but empty fields (read elsewhere, not editable). The drop check compares only rows underdatasource.childrenwith the datasource's own children; a query that reads another path is reported as not checked. Exit 1 on a drop, non-jsonValuerows or a rejected query; exit 2 when the route does not resolve or not one row count could be verified. A resolver payload is a WARN: the tool reports, the stop condition below decides. - For class A, open Pages, select the component, add a row in Manage items, reorder it, edit a row field inline. This by-hand check is the proof (done on a tabs list 2026-11-04: inline edit and reorder worked; adding a row was not separately reported). To see the evidence, inspect a row field in the canvas and look for the field chrome. An App Router app fetches layout data on the server, so the layout JSON is not in the browser's network tab;
--editing-layout <file>is for a layout logged server-side in editing mode. Expect the edit to write to the CM [measured 2026-11-04, from the pull diff]: reordering sets__Sortorder, a rich text edit wraps the value in<div class="ck-content">, and Pages adds a thumbnail under the mediaSystemfolder.ser pullafterwards, or the next push overwrites them. - For class B and D, confirm the "Edit source" link in editing mode and that a newly published item appears after revalidation.
Stop conditions
- The component must show more rows than the budget allows and each row must be editable inline: that is two components (a curated class C surface over a class D library), not one.
- The probe warns of a resolver payload on a tenant that uses Edge runtime publishing: treat that warning as a blocker and replace the resolver before anything else.
- A row field cannot be edited inline in Pages: check it is selected as
jsonValueand rendered through an SDK field component with noeditable={false}, then fall back to Manage items plus the source item.
Cross-references
content-sdk-list-component: building a class A component (templates,__Masters, branch, Manage items bases, verify script).content-sdk-resolver-patterns: payload shapes a component receives.content-sdk-navigation-component,content-sdk-app-router-component-level-navigation: menus and other tree-derived navigation.sitecoreai-edge-graphql-capture§ 2b: the measuredComponentQuerybudget table.content-sdk-app-router-cache-components-and-osr: revalidating server-fetched lists on publish.
Content SDK — Component Naming Traps
The sitecore-tools generate-map step that produces .sitecore/component-map.ts is silent about its assumptions, and easy to violate. Worse, the map is generated, so a broken registration changes no hand-written file and survives lint, tests and the build untouched — the failure surfaces only as an empty component at runtime.
When to use
- Adding any new file under
src/components/. - Refactoring or relocating UI infrastructure (theme providers, layout shells, design system primitives).
- A new Sitecore rendering appears on a page but the head app can't find the component (likely a name-mismatch).
- The component-map.ts has surprising entries you didn't intend.
How to perform
- Before placing a new file, decide: is it a Sitecore rendering, or is it infrastructure?
- Sitecore rendering (matches a
componentNamein the layout response):src/components/<ComponentName>/<ComponentName>.tsx. Gen-map will register it. - Infrastructure (theme provider, site chrome, ResolverProbe, design system primitives, helpers):
src/ui/,src/site/,src/lib/, or any path NOT incomponentMap.paths. Gen-map will ignore it.
- Sitecore rendering (matches a
- Run
npm run sitecore-tools:generate-mapafter creating/moving files. Inspect.sitecore/component-map.ts— every entry should correspond to a real Sitecore rendering. - For renderings with spaces in
componentName(e.g.Datasource Content Resolver), name the folder + file with the spaces preserved. Gen-map produces:- An import alias with spaces stripped (e.g.
DatasourceContentResolver). - A map key with the spaces PRESERVED (e.g.
'Datasource Content Resolver') so runtime lookup matches the layout response exactly. - This preservation applies to SPACES ONLY.
toPascalCasesplits on[-_]and nothing else, so a space survives into the key while an underscore or hyphen does not. Do not generalise this bullet into "the key always mirrors the filename" — see trap 6 below.
- An import alias with spaces stripped (e.g.
- For variant files, use the
<ComponentName>.<VariantName>.tsxconvention. Gen-map merges them into one map entry:['ComponentName', { ...Default, ...Variant1, ...Variant2 }]. The runtime picks the right export byparams.FieldNames.
Hard Rules
sitecore.cli.config.tsdeclarescomponentMap.paths— usually['src/components']withexclude: ['src/components/content-sdk/*']. Anything under a scanned path is a candidate Sitecore rendering. Anything underexclude(or outside the scanned paths entirely) is invisible.- Never put UI infrastructure under
src/components/. It will register as a Sitecore rendering named e.g.theme-toggle, which (a) is wasteful, (b) might collide with a future real rendering of that name. Put it insrc/ui/,src/site/, etc. - Don't hand-edit
.sitecore/component-map.ts. It's regenerated on everynpm run dev/npm run build. Edits are lost. Adjust source structure orsitecore.cli.config.tsinstead. - Map key === rendering
componentNameexactly — including spaces, casing, hyphens, and underscores. Mismatch → empty component placeholder at runtime. - NEVER put
_or-in a component folder/file name. On@sitecore-content-sdk/content2.2.x the key istoPascalCase(filename), which splits on[-_], soNavigation_Custom.tsxregisters asNavigationCustom, and no filename can produce a key containing an underscore or hyphen — the split is unconditional. Content 2.3.0 reverted this (key = the verbatim file name,moduleNamestill PascalCased) and left a TODO to re-enable it at the next major, so an underscored name works today and breaks again on the 3.0 bump. The safe name is the one that is right under both rules. If a rendering'scomponentNamehas one, the rendering must be renamed on the CM (Authoring GraphQLupdateItemon thecomponentNamefield); renaming the folder alone cannot fix it. Rename the rendering item at your peril — its path and its<X> Parameterstemplate are path/GUID-coupled, and page layouts reference the rendering by GUID, so changing onlycomponentNameis the safe minimal edit. - Folder name === file name (within the folder) for the gen-map to pick up the base component. Variant files add
.<Variant>to the basename. - When in doubt, check the live layout response (
content-sdk-debug-layout-probeskill) to find the exactcomponentNamestring before naming the folder. - Only the Sitecore-registered
.tsxfile (and its.<Variant>.tsxsiblings) belong insidesrc/components/<Component>/. Every other file — types (*.types.ts), GraphQL queries (*.gql.ts), sub-components (e.g. a client-sideNavBranch.tsx), server actions, route-handler logic, helpers — MUST live outside that folder. Recommended homes:src/lib/<feature>/for non-React code + tightly-coupled internal components;src/ui/for cross-cutting UI primitives;src/app/api/for route handlers. The same holds for starter folders: the integrated-search starter'ssearch-experience/search-components/placed undersrc/components/registers every hook and helper as a rendering (content-sdk-search). Atoms (beta.atoms) live insrc/atoms/, outsidesrc/components/and outside the map; never move them in (content-sdk-app-router-atoms). Otherwise gen-map sees the support files and either (a) registers them as separate top-level Sitecore renderings (e.g.['NavBranch', { ... }]) or (b) interprets them as variants of the main component (e.g.*.types.tsis seen as varianttypes) and spreads their non-React exports into the main map entry, polluting it. - Avoid generic single-word rendering-parameter names like
Levels,Depth,Style,Type,Items. They can silently collide with base-template fields (or SXA standards likeLevelFrom,LevelTo,Styles,EnabledPlaceholders) and become invisible in Pages even though the field exists in the template. Use namespaced names (NavDepth,NavMaxItems) or singular forms (Levelworked,Levelsdid not in one verified case). When in doubt, scope-prefix.
Stop Conditions
- Stop and ask if the
componentNamefrom the rendering contains characters that aren't valid in file paths on Windows (e.g.<>:"|?*). Suggest the user rename the rendering in Sitecore first. - Don't relocate the existing
src/components/content-sdk/folder — it holds SDK-provided helpers (CdpPageView, SitecoreStyles) and is explicitly excluded insitecore.cli.config.ts. - Don't create a component with a
componentNamethat matches a built-in (BYOCWrapper,FEaaSWrapper,Form) — those are always registered first and your version will be shadowed.
Verification
- After moves/edits, run
npm run sitecore-tools:generate-mapand read.sitecore/component-map.ts. Every key should be a Sitecore rendering name; no infrastructure names should appear. - Build the app (
npm run build) and check the "Registering Content SDK component " log lines. They list every key being registered — if there's a surprise, fix the source. - After ANY SDK upgrade,
git diff .sitecore/component-map.*and treat a changed KEY as a breaking change, not regeneration noise. The key derivation is version-sensitive (trap 6), and a one-line key change passes every other gate. - Reconcile keys against the CM. Every rendering's
componentNamemust appear as a key. Cheapest source is a live layout response (content-sdk-debug-layout-probe) or the serialized rendering YAML; a mismatch is a guaranteed runtime blank. Worth a committed snapshot test of the key list so silent changes fail the PR. - ⭐ The only check that PROVES the match is rendering a real page. A local test can assert the key set and ban
[-_]filenames, but it cannot know what the CM calls a rendering — that lives in another system (often another repo, absent in CI). Do not fake it with a conditional skip; a test that silently no-ops in CI is worse than none. Instead smoke the PR's preview deployment and assert noMissingComponentplaceholder appears on any route. That is the reconciliation, performed empirically. Seecontent-sdk-website-build-flow§ "Gate the PR preview deployment" for the harness, the honest-target precondition, and the pixel-diff trap.
Worked example #1 — the spaced-name pattern
Rendering with componentName: "Datasource Content Resolver":
- Folder:
src/components/Datasource Content Resolver/ - File:
src/components/Datasource Content Resolver/Datasource Content Resolver.tsx - Gen-map output:
import * as DatasourceContentResolver from 'src/components/Datasource Content Resolver/Datasource Content Resolver'; // ... ['Datasource Content Resolver', { ...DatasourceContentResolver }], - The alias is sanitized; the path is preserved (paths with spaces are valid in TS imports when handled by Webpack/Turbopack); the map key matches the layout response.
Worked example #2 — the support-files pitfall (and the relocation that fixed it)
⚠ The name in this example is itself a trap. It is shown verbatim as it happened, on a component then called
Navigation_Custom. Do not copy that name — the underscore is exactly what trap 6 forbids, and it later broke this component outright on an SDK upgrade. The support-files lesson below is independent of the name and still correct; the component has since been renamedNavigationCustom.
Building a navigation component, the first scaffold colocated four support files alongside the Sitecore-registered component file:
src/components/Navigation_Custom/
Navigation_Custom.tsx ← intended: the only Sitecore registration
Navigation_Custom.types.ts ← types
Navigation_Custom.gql.ts ← GraphQL queries
NavBranch.tsx ← client component (dropdown logic)
actions.ts ← Server Action (later switched to a route handler)
After running generate-map, .sitecore/component-map.ts contained:
import * as Navigation_Customtypes from 'src/components/Navigation_Custom/Navigation_Custom.types';
import * as Navigation_Customgql from 'src/components/Navigation_Custom/Navigation_Custom.gql';
import * as Navigation_Custom from 'src/components/Navigation_Custom/Navigation_Custom';
import * as NavBranch from 'src/components/Navigation_Custom/NavBranch';
import * as actions from 'src/components/Navigation_Custom/actions';
export const componentMap = new Map<string, NextjsContentSdkComponent>([
// ...
['Navigation_Custom', { ...Navigation_Customtypes, ...Navigation_Customgql, ...Navigation_Custom }],
['NavBranch', { ...NavBranch, componentType: 'client' }], // ← unintended Sitecore rendering
['actions', { ...actions }], // ← unintended Sitecore rendering
// ...
]);
Two distinct failure modes simultaneously:
-
*.types.tsand*.gql.tsgot interpreted as variants ofNavigation_Custom(because the basename pattern<Component>.<X>.<ext>matches the variant-file convention). Their non-React exports (NavItemtype,NAV_LEVEL_1_QUERYstring) got spread into theNavigation_Custommap entry, polluting its export surface —componentMap.get('Navigation_Custom').NAV_LEVEL_1_QUERYbecomes a string. Settingparams.FieldNames="types"in a rendering instance would attempt to "render" the types module as a React component. -
NavBranch.tsxandactions.tsgot registered as standalone Sitecore renderings namedNavBranchandactions. If an author ever named a real renderingNavBranchit would collide. Even without collision, the SDK now believesNavBranchis a routable component, which it absolutely is not.
The fix — relocate all support files outside src/components/:
src/
components/
Navigation_Custom/
Navigation_Custom.tsx ← only this file remains here
lib/
navigation/
types.ts ← was Navigation_Custom.types.ts
queries.ts ← was Navigation_Custom.gql.ts
nav-branch.tsx ← was NavBranch.tsx (still a 'use client' component, just lives in lib/)
app/
api/
nav-children/
route.ts ← was actions.ts (re-architected as a route handler — read-only fetches should never be Server Actions; see content-sdk-app-router-route-handler-vs-server-action)
After regen, .sitecore/component-map.ts is pristine — ['Navigation_Custom', { ...Navigation_Custom }] with no extra imports. The fix is purely structural (file paths); the runtime imports in the component file change from ./types to src/lib/navigation/types, but the actual code is unchanged.
Generalisable rule: src/components/<Component>/ is for the Sitecore-registered React component and its variant siblings — nothing else. The moment you reach for a .types.ts, .gql.ts, .client.tsx, actions.ts, helpers.ts to put alongside, send it elsewhere first.
Worked example #3 — trap 6: the underscore an SDK upgrade ate
Version window, measured from the installed source. @sitecore-content-sdk/content 2.2.x (shipped with nextjs 2.3.0) derives the key with toPascalCase; content 2.3.0 (with nextjs 2.4.0) sets componentName: name again — the verbatim file name — with a // TODO: enabled using toPascalCase() … with NextJS CSDK major release beside it (verified 2026-09-18 in dist/esm/tools/templating/components.js across three apps on content 2.3.0, and one of them carries a working ['Navigation_Custom', …] key). So the trap fires in one minor window today and is announced to return at 3.0. It has not returned in the 3.0.0-beta.atoms stamp (measured 2026-10-02): Foo_Bar.tsx → key Foo_Bar verbatim, and dotted files are keyed by prefix, not dropped (Promo.WithText.tsx → Promo as a variant, foo.component.tsx → foo). scripts/assert-map-keys.mjs reads the rule off whatever is installed instead of trusting this paragraph.
A head app carried src/components/Navigation_Custom/Navigation_Custom.tsx against a rendering whose componentName was Navigation_Custom. It worked for months on SDK 2.2. The 2.2 → 2.3 bump (nextjs versions; content 2.1 → 2.2) regenerated the maps and produced:
-import * as Navigation_Custom from 'src/components/Navigation_Custom/Navigation_Custom';
- ['Navigation_Custom', { ...Navigation_Custom }],
+import * as NavigationCustom from 'src/components/Navigation_Custom/Navigation_Custom';
+ ['NavigationCustom', { ...NavigationCustom }],
The nav disappeared from every page of a live site, and Page Builder showed "Content SDK component is missing React implementation."
The mechanism — the key is toPascalCase(filename), and the split is unconditional:
// @sitecore-content-sdk/content/dist/esm/tools/templating/components.js
const toPascalCase = (name) => name.split(/[-_]/)
.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
// componentName: toPascalCase(name) ← the MAP KEY
// moduleName: toPascalCase(name).replace(/[^\w]+/g, '') ← the import alias
Lookup is an exact Map.get(rendering.componentName) with no normalization, so it misses and the placeholder falls back to MissingComponent.
Why nothing caught it. The only changed file was generated, and nothing in src/, the e2e suite or the tests asserted a map key. Lint, 814 passing tests, a clean build and an unchanged SSG route count all stayed green across the break. The upgrade was even recorded as "package-only — no source file changed", which was true of src/ and blind to a generated file changing semantics.
Proven by control, not inference: a sibling app held the identical folder, stayed on ^2.2.0, and kept the correct key. One variable changed.
The fix. Because no filename can yield an underscored key, the rendering moved: componentName → NavigationCustom via Authoring GraphQL, and the component renamed to match so the key is right by construction. The rendering item name, its path and its <X> Parameters template were deliberately left alone — all path/GUID-coupled, and layouts reference the rendering by GUID, so authored pages were unaffected.
Two publish traps met on the way out:
- Publishing the rendering item alone did nothing —
Completed, 0 processed. The layout Edge serves is composed when the PAGE is published; it took the site'sHome --children. - Correct Edge data does not mean a correct site. Live Edge was right on 12/12 routes while the public site still served build-time HTML (
x-vercel-cache: HIT,age: 2070,x-nextjs-prerender: 1). Those SSG routes carried norevalidate, so they never refreshed — only a redeploy did.
Prevention: after ANY SDK upgrade, diff .sitecore/component-map.* and reconcile the keys against the renderings' componentName. A one-line key change is invisible to every other gate. scripts/assert-map-keys.mjs --app <head-app> --renderings <serialized renderings dir> does the reconciliation (exit 1 on a componentName with no key, WARN on a [-_] filename because the rule is version-sensitive); content-sdk-upgrade-assistant's upgrade-surface.mjs prints the key rule of the installed and the target package side by side.
Related
content-sdk-app-router-component-scaffold— the canonical scaffold instructions.content-sdk-app-router-component-registration— how the map is consumed at runtime.content-sdk-debug-layout-probe— to discover the exactcomponentNamefrom a live response.content-sdk-website-build-flow§ "Gate the PR preview deployment" — the CI gate that catches a key/componentNamemismatch empirically, which no local check can.
References
scripts/assert-map-keys.mjs— keys vs serializedcomponentNamevalues, plus the installed key rule; dependency-free Node..sitecore/component-map.ts— generated output (do not hand-edit).sitecore.cli.config.ts—componentMap.paths+excludeconfig.
Content SDK — Component Review
The costly defects on this stack all render correctly: a component an author cannot edit, a datasource that lands in another site's tree, a list whose rows nobody can add, a template whose base chain resolves to nothing. Build, unit tests and a code review of the diff all pass. This skill is the review pass for the Sitecore artifact, not just the code: rendering item, templates, head-app component and serialization, judged together.
It is the counterpart of content-sdk-feature-planner: the planner decides before the build, this checks the build against the same axes.
When to use
- Before merging or promoting a new or changed component (rendering + templates + head-app code + serialization).
- When taking over a component someone else built ("is this actually authorable?").
- As the review step of a delivery loop, per component.
Not for: the health of a whole environment or site (sitecoreai-health-check), debugging a component that misbehaves (content-sdk-troubleshooting), deciding what to build (content-sdk-feature-planner).
Inputs
| Input | Required | Use |
|---|---|---|
| Component name + head-app path | yes | src/components/<Name>/, the component map |
CM path (<cm>/authoring/items/) | yes | rendering item, templates, branch, Standard Values as YAML |
| The planner's blueprint | no | when present, review built vs planned row by row: every decision row is a check, and a row the build silently changed is a finding |
| Expected tenant + Authoring endpoint | for the live leg | the binding proof below |
Without a blueprint, review against the planner's decision axes; the axis table below follows them.
Verdicts, not a score
Each axis gets PASS / FAIL / UNKNOWN, with a severity P0–P3 on a FAIL (same scale as sitecoreai-health-check):
| Sev | Means |
|---|---|
| P0 | broken for every author or visitor now (component un-editable, renders nothing, base chain empty) |
| P1 | breaks a real author task or the next push (no way to add a row, datasource in the wrong tree, a push that strands items) |
| P2 | degraded or risky (raw .value on one field, missing editing escape on a guard, a waiver without a reason) |
| P3 | hygiene (comment walls, icon gaps, density) |
UNKNOWN never counts as a pass. A script that could not run, a missing credential or an axis you could not evidence is UNKNOWN, and stays visible in the report. A score would hide the one failing field behind a good average; a verdict per axis cannot.
The axes
Full checks, evidence sources and default severities: references/axes.md.
| # | Axis | Leg | Owning skill |
|---|---|---|---|
| A1 | Authorability: every authored value arrives on fields and renders through an SDK field component; exceptions per field, each with a reason | static + human | — (scripts/audit-component-authorability.mjs) |
| A2 | Editing safety: renders in Pages edit, preview and the design library; empty fields stay selectable | static + human | content-sdk-app-router-editing-safe-rendering |
| A3 | Registration and naming: component map key = componentName; only registered .tsx under src/components/<Name>/ | static | content-sdk-component-naming-traps |
| A4 | Variant vs sibling: one rendering with variants, or a deliberate sibling; variant file naming | static | content-sdk-variants-vs-siblings |
| A5 | Data strategy: plain fields vs resolver vs ComponentQuery; no fetch replacing fields; Edge depth budget | static | content-sdk-resolver-patterns |
| A6 | Content model and scoping: Datasource Template is a path, Datasource Location is site-relative (no hard GUID pin), params template linked, local datasources under <Page>/Data, shared renderings forked not mutated | static + live | content-sdk-create-component |
| A7 | List wiring (list components only): the four legs | static + live + human | content-sdk-list-component |
| A8 | Template integrity: every project template's base chain resolves in the live engine | live only | — (scripts/check-template-base-chain.mjs) |
| A9 | Serialization completeness: rendering, templates, branch, placeholder settings and Standard Values all covered; a template is serialized wherever its items are | static | sitecoreai-serialization |
| A10 | Comment economy: a comment says WHY in a line or two; walls are a smell | static | — (scripts/audit-comment-density.mjs) |
| A11 | Cross-cutting, where relevant: dictionary keys with a literal default, personalization scope, consent gating, cache tags | static | per concern (see references/axes.md) |
Mandatory axes (an UNKNOWN blocks promotion): A1, A2, A3, A6, A8, A9, and A7 for a list component.
Procedure
1. Scope the unit
Name the component and collect its parts: src/components/<Name>/*, the map entry, the rendering item, its datasource template(s), params template, branch (list components), Standard Values, and the module include that should cover them. A part you cannot locate is already a finding (A9 or A6).
2. Static leg: run the bundled scripts
node scripts/audit-component-authorability.mjs --app <head-app> --json # A1, A2 (guards), A11 (literal microcopy)
node scripts/audit-sitecore-schema.mjs --cm <cm> [--brand <b>] --json # A6, A7 (grouping base), A9 hints, icons
node scripts/audit-comment-density.mjs --path <head-app>/src/components/<Name> --json # A10
Exit codes: 0 clean, 1 findings, 2 harness or waiver-file error (treat 2 as UNKNOWN on the axes that script owns). Filter the output to the component under review; the scripts audit the whole app or CM. A clean run on a brand with zero renderings is not a pass: the schema audit fails that case by design.
Then read the code and YAML for what no script sees: A3 map key vs componentName, A4 variant naming, A5 data shape, A9 module coverage (ser explain -p <path> names the owning module), A11.
3. Live leg: read-only, bound to one tenant
Run only when the component exists on a tenant. Prove which tenant you read before you trust any answer:
- Pass the expected tenant explicitly; never infer it from a hostname or a default profile.
scripts/check-template-base-chain.mjsrefuses to run (exit 2) unless the token's tenant claim matches--expect-tenant.- Use a known-good and a known-bad control: one item you know exists must come back, one path you know does not must come back null. An instrument that cannot return "missing" proves nothing.
- Never write. No mutation, no publish, no
ser push. A fix is a separate step with its own owner.
SITECORE_CLIENT_ID=… SITECORE_CLIENT_SECRET=… \
node scripts/check-template-base-chain.mjs --cm <cm> --expect-tenant <tenant-name> --brand <b> --json # A8
Credentials may also come from --env-file <file>. --endpoint overrides the Authoring GraphQL URL, which otherwise derives from the bound tenant (https://xmc-<tenant>.sitecorecloud.io/…). Exit 2 means could not check (no templates found, refused binding, query error), never a broken chain: measured 2026-10-13, the wrong tenant was refused and the right one checked 90 templates with 0 broken.
Credentials: a client-credentials automation client (sitecoreai-auth). Then read the rendering item, Standard Values and list legs with the queries in references/live-recipes.md (A6, A7). Why A8 must be live: Content Serialization writes __Base template one GUID per line either way, so a correct and a broken live value serialize to identical YAML.
4. The human check
Acceptance line: an author can find and change every value. A static PASS on A1, A2 or A7 is necessary, not sufficient. For a new component, one person opens it in Pages, selects each field and edits it, and for a list adds a row. Record the result as evidence; without it A1/A2/A7 cap at PASS (static) and the report says so.
5. Built vs planned (blueprint present)
Walk the blueprint's decision table. For each row: what was decided, what was built, MATCH / DRIFT. A drift with a recorded reason is fine; a silent drift is a P2 finding (P1 when it moves a datasource, the list legs or the module).
6. Report and gate
Write the report in the shape of references/output-format.md. Gate: any P0 or P1 FAIL, or any UNKNOWN on a mandatory axis, means not promotable. Each finding names an owner: code (head app) or cms (items, templates, serialization).
Waivers
Each script reads a waiver file beside its target, and every entry needs its own reason:
| Script | File | Where |
|---|---|---|
| authorability | .authorability-ignore.json | head-app root; components and per-field fields ("<Component>.<Field>") |
| schema | .schema-audit-ignore.json | CM root; loose datasources carry their own reason |
| comment density | .comment-density-ignore.json | the audited path |
An entry without a reason makes the script exit 2. A waiver that no longer matches anything is reported as stale: remove it. In the review, list every waiver that touches the component; a waiver whose reason does not hold up is a finding, not a pass.
Gotchas
- The scripts audit the whole app or CM. A component can look clean while its neighbour fails; filter by component, and report findings outside the scope separately rather than dropping them.
- A1 cannot prove the right fields are rendered, only that field components are used. It also cannot prove inline editing works on the canvas: that is the human check.
- Do not "fix" the schema audit's lenient
__Base templateparser. It must accept both separators, or every correctly serialized brand fails; the live A8 check is where a broken chain shows. - Preview is permissive. A component that renders on preview has proved nothing about live delivery; that is
content-sdk-troubleshootingterritory, not a review verdict.
References
references/axes.md: per axis, what to check, evidence, default severity, script or skill.references/live-recipes.md: read-only Authoring GraphQL queries for A6–A8.references/output-format.md: output layout, finding schema, gate rule.- Related:
content-sdk-feature-planner(blueprint),sitecoreai-health-check(environment doctor),content-sdk-troubleshooting(symptoms),sitecoreai-graphql-schemas(shapes).
Sitecore Create Component (clone an OOTB rendering, then customize — via Authoring+Management GraphQL)
This skill creates a new component in SitecoreAI. The canonical method is to clone an OOTB component and then customize it to match the component you want — it is more than a plain clone: you copy a wired source, then replace its datasource fields with the new component's field set so the result is the target component, not a duplicate. Per Sitecore's own Accelerate guidance, every component should start as a clone of an OOTB one, because cloning wires up all the base templates needed for the full authoring feature set. The SPE "Clone Rendering" script does only the clone half in the Content Editor; this skill does the full clone-and-customize headlessly via the Authoring+Management GraphQL API so a component can be created end-to-end and automated. (Building a component from scratch with the Marketer MCP is the alternative — see below.)
- Clone Promo for a component backed by its own datasource item (the common case).
- Clone PageContent for a context-only / no-datasource component.
Verified end-to-end on a live tenant by diffing a real clone against its Promo source (full custom-field clone + derive-clone-shape from any tenant).
What cloning copies (the bundle)
A faithful clone is four copied items + relinks, not a single item copy. Template folder layout — everything lives inside the site's own templates folder /sitecore/templates/Project/<Brand>/<Site>/:
- Datasource template (
…/<Site>/<Name>) — the field set. Datasource templates and list element (child/row) templates sit at the root of the site folder. - Folder template (
…/<Site>/Folders/<Name> Folder) — holds datasource items; its__Standard Values.__Mastersis the insert-options list (= the datasource template, so the component's own datasource is the only thing an author can add under it). All folder templates live in aFolders/subfolder. - Parameters template (
…/<Site>/Rendering Parameters/<Name> Parameters) — rendering params. All parameters templates live in aRendering Parameters/subfolder. - Rendering definition (
/sitecore/layout/Renderings/Project/<Brand>/<Site>/<Name>, templateJson Rendering).
✅ Content SDK: create the parameters template, LINK it, and FORCE-publish it — works IFF three conditions hold. Clone the
<Name> Parameterstemplate intoRendering Parameters/and set the rendering'sParameters Templatefield = its{GUID}. Reliable delivery through Experience Edge requires ALL of: (a) the params template inherits the 4-base HEADLESS set (clone from JSS Experience Accelerator, not the MVC 8-base one — Edge can't serializeIStyling/Grid Parameters/IComponentVariant/ICacheable); (b) the rendering'sDatasource Templateis an item PATH, not{GUID}; (c) the params templates are force-republished to Edge in their current 4-base state (dotnet sitecore publish item -p {templatesRoot} -sub -rel -r). Miss any — especially (c): a smart publish can leave a stale broken 8-base definition in Edge — and Edge'slayoutquery silently drops the whole route (route=undefined, no error → every page blank). This was the entire "params link breaks the page" saga (one brand, 2026-07-17 → resolved 2026-07-20). (In classic SXA/Pages authoring — non-Content-SDK — the always-link rule still holds; this carve-out is Experience-Edge/Content-SDK-specific.)
Two modes (independently for parameters and datasource):
- Make a copy — full
copyItemof the template (extend/reorder fields). Recommended default; decouples from the source. - Inherit — create a new template whose
__Base templatepoints at the source (restyle only).
NOT auto-handled by the clone: rendering variants (Headless Variants — create separately) and the head-app .tsx + component-map registration (componentName must map to a React component or it renders MissingComponent). Available-Renderings registration and icon assignment (§ Icons) are explicit steps (below).
Base-template inheritance (authoritative — verified from OOTB Promo + Link List)
Every created/cloned template MUST end up with exactly these __Base template sets. Cloning the matching OOTB source yields them automatically — read the result back and assert the set (introspect the exact GUIDs per tenant; never create from scratch inheriting only Standard template).
⚠️ Clone from the HEADLESS SXA tree —
/sitecore/templates/Feature/JSS Experience Accelerator/…— NOT the classic/sitecore/templates/Feature/Experience Accelerator/…(MVC). The MVC Promo Parameters carries 8 bases (Standard Rendering Parameters+IStyling+Grid Parameters+IComponentVariant+IDynamicPlaceholder+IRenderingId+ICacheable+_PerSiteStandardValues); the headless JSS Promo Parameters carries the 4-base set in the table below. Cloning the MVC source gives bloated, wrong inheritance that headless doesn't use (measured 2026-07-17). This matters most for the Rendering Parameters rows; assert the exact set after cloning.
| Template kind | Clone source (JSS Experience Accelerator) | __Base template (exact) |
|---|---|---|
| Standard datasource | Promo | Standard template + _PerSiteStandardValues |
| Standard datasource — Rendering Parameters | Promo Parameters | Base Rendering Parameters + IDynamicPlaceholder + _PerSiteStandardValues + IRenderingId |
| List / collection container (Link List / IGQL children) | Link List | Standard template + _PublishingGroupingTemplate + _HorizonDatasourceGrouping + _PerSiteStandardValues |
| List / collection element (child / row) | Link (element) | Standard template + _PerSiteStandardValues |
| List / collection — Rendering Parameters | LinkList Parameters | Base Rendering Parameters + _PerSiteStandardValues + IRenderingId |
The asymmetry is intentional: the standard params template includes IDynamicPlaceholder; the list params template does not. _HorizonDatasourceGrouping (on the container, never the element) is what makes a list + its children inline-editable in Pages/Horizon. Base Rendering Parameters is what makes Page Builder recognize the template as rendering parameters at all — a params template on only Standard template is invisible in Page Builder.
List / collection components (the Link List pattern)
The full Link List pattern — element template, container→element insert options, branch datasource, children-aware delivery (ComponentQuery) — is in references/list-components.md. Decide first whether the rendering IS a list (the content-sdk-list-component skill carries the four legs); open the reference only when it is.
Endpoint + auth
POST https://<tenant-cm-host>/sitecore/api/authoring/graphql/v1, Authorization: Bearer <JWT>. OAuth client-credentials, audience https://api.sitecorecloud.io, scope incl. xmcloud.cm:admin (see sitecoreai-auth). No publish needed for the component to appear in Pages — Pages reads the authoring DB. Publish only for delivery.
The verified GraphQL sequence
The copy-ready mutation sequence (clone templates → relink → register in Available Renderings → swap the field set) is in references/graphql-sequence.md. Read it when executing; the sections around this one carry the decisions the sequence assumes.
Before any raw field write, read that file's § "Write-side wire formats". Authoring GraphQL accepts a wrong value silently. Every GUID must be braced, dashed and uppercase. Multi-value fields must be |-joined, never newline-joined. Children created over AGQL need __Sortorder. General Link XML needs &, and mailto: links need linktype="mailto". Each wrong form breaks the page, the Pages picker or inheritance without an error.
Standard Source settings by field type (apply by default)
When creating datasource fields, set the field's Source to the standard SXA data-grab query for its type, unless told otherwise. For any picker/list field the Source is REQUIRED — it defines the available choices, and it only accepts items or (fast/relative) queries that resolve to items.
| Field type | Source |
|---|---|
| Rich Text | query:$xaRichTextProfile |
| Image | query:$siteMedia |
| General Link | query:$linkableHomes |
| Single-Line / Multi-Line Text | (none) |
| Checkbox | (none) |
| Multilist / Treelist / Droplink / Droptree (list of pages / items) | a query resolving to the choices — query:$linkableHomes for pages, or a relative template-filtered query:./*[@@templatename='<ChildTemplate>'] for the datasource's own children. NEVER leave it unset or a fixed root path (the Pages picker then lists content-tree roots instead of the real choices). |
Rendering-parameter Source rules
Rule of thumb — rendering parameter vs datasource field. A rendering parameter controls styling / behavior (color, size, alignment, on/off) and is a Single-Line Text, Checkbox, or Droplink over a fixed choice set. A datasource field holds content (text, image, link, child items). A param that needs a fixed list of choices → a Droplink + the option-items pattern below; never a datasource field, and never the literal value in
Source.
Parameter fields obey the SAME Source law as datasource fields: the Source only accepts items or (fast/relative) queries that resolve to a list of items — it is NOT a slot for a literal flag value. Pick the field TYPE for the interaction, and the Source to match:
| Param intent | Field type | Source |
|---|---|---|
| Boolean flag (e.g. sort Ascending — unchecked = descending) | Checkbox | (none) |
| Free text / numeric token | Single-Line Text | (none) |
| Enumerated choice (sort order as a dropdown, colors, sizes) | Droplink / Droplist | a folder of option items (below) |
Never encode a boolean or enumeration in the Source field. A Source of Ascending/Descending is invalid — Sitecore tries to resolve those as item paths and the field renders no usable options. For a true on/off flag use a Checkbox (default unchecked = the "off" / descending state).
Enumerated parameters — the option-items pattern (reusable for sort order, colors, sizes, alignment…):
- Under the site's
Rendering Parameters/folder, create aContentfolder, and inside it one folder per list — e.g.Rendering Parameters/Content/Colors,…/Sizes,…/Alignments. - Create one item per choice inside that list folder, from a small
Rendering Parameter Entrytemplate that carries aValuefield (e.g.Left→Valueleft,Center→center; orAscending→asc). - On the params template, make the field a Droplink / Droplist whose
Source=query:/path to that list folder (e.g.…/Rendering Parameters/Content/Alignments).
The head app reads the selected item's Value. One list folder is reusable across components (a shared Alignments serves every component's alignment param). This is how you offer any fixed choice set without abusing the Source field.
Tenant-specific ids — introspect, don't hardcode
These vary per tenant; resolve them on the target before cloning:
- "Template section" template id — often
{E269FBB5-3750-427A-9149-7AA950B49301}(stable Sitecore id, but verify per tenant). - "Template field" template id — often
{455A3E98-A627-4B40-8035-E683A0331AC7}, which can differ from the textbook{455A3E98-…-58A708D5E84B}— so read it off an existing field item (item(...Promo/Promo/Title).template.templateId), never assume. - The source rendering + its DS/folder/params templates, the project module's template + renderings folders, and the Available-Renderings group id — discover via
item(where:{path})+children. - Field
Typeis set by the field value "Type" ="Single-Line Text"/"Rich Text"/"Image"/"General Link"/ … (the human-readable type name).
Cleanup-order gotcha (deleting a clone)
You cannot delete a cloned template while items are based on it or link to it. Delete bottom-up:
- the rendering (also de-register it from Available Renderings; this drops its
Datasource TemplateInternal Link), - every item based on the datasource template — its own
__Standard Values, any authored datasources, and the Design LibraryMock-<ComponentName>datasource (see below). The reliable way to find them all is an Authoringsearchon_template= the template id (32-hex, no braces/dashes) and delete each hit, - the folder template, then the datasource template (sections/fields cascade),
- the parameters template.
Skipping step 2 yields "The '<id>' template is used by at least one item. Delete all the items that are based on this template first."
The Design Library auto-creates a mock datasource. When a component is registered in Available Renderings, SitecoreAI's Design Library generates a
Mock-<ComponentName>-<guid>item based on the datasource template under/sitecore/system/Settings/Foundation/Design Library/Data Sources/. It is invisible as a child of the template (it lives elsewhere) but blocks the template delete —deleteItemkeeps returning "used by at least one item" with no obvious culprit. Search_templateto find it. (This is also why a freshly created component already previews with sample content in the Design Library.)
The Marketer MCP CAN build a component too — it just has no clone primitive
Tested empirically by building + configuring + registering a working rendering end-to-end with only Marketer MCP tools:
create_content_item(name, templateId, parentId, fields)is generic — it creates ANY item: a rendering definition (Json Rendering), a datasource template (Template), aTemplate section, andTemplate fielditems (withType+Sourceset viafields). All verified on the tenant.update_fields_on_item(itemId, fields)is generic — it writes ANY field on ANY item: the rendering'scomponentName/Datasource Template/Datasource Location/Parameters Template, and the Available Renderings group'sRenderingsfield → the rendering became placeable in the Pages picker (confirmed viaget_allowed_comps_by_ph).delete_content(itemId)removes items.
So the MCP can construct + configure + register the entire bundle from scratch. The single thing it lacks is a clone/copy primitive (no copyItem): it cannot duplicate an OOTB component's already-wired template subtree in one shot, so you build each item and set each field individually — and you must supply the correct base-template ids / field types yourself (which a clone inherits for free).
When to use which:
- GraphQL
copyItem(this skill) — true Clone Rendering: copy a wired OOTB component (Promo / PageContent) + relink. Fewest calls, inherits the correct base templates, highest fidelity. Best for "clone an existing component." - Marketer MCP (
create_content_item+update_fields_on_item) — build a component piece-by-piece + register it. Best when you're already in an MCP/agent context. Best for "create a component" from a known field spec.
MCP quirks (verified): update_fields_on_item (and the Available-Renderings write) return misleading/empty updatedFields payloads even on success — always verify via a read, not the response. get_content_item_by_path returns fields: {} (no raw field values), so read-modify-write of a multilist (e.g. appending to Renderings) needs the current value from GraphQL or another source.
Either way, get_allowed_comps_by_ph(pageId, placeholderName) is the placeability verifier.
Icons
Pick ONE icon per component and apply it CONSISTENTLY to every item the component owns — the rendering, the datasource template (+ its __Standard Values), each list-element template (+ SV), the folder template (+ SV), and the parameters template (+ SV). One component = one icon everywhere (a Timeline shows calendar on its rendering, datasource, folder, and params alike) → the Pages palette + content tree read cleanly. Setting the icon on each template's __Standard Values too is what makes the instances (datasource content items, global containers) inherit it. Use content-sdk-icon-chooser: tokenize the component name → semantic category → updateItem __Icon. Required Definition-of-Done step, not a nicety — a wall of identical default icons makes the Pages palette unreadable.
⚠️ Verify the icon name EXISTS in this tenant's icon set — a missing name renders BLANK (looks like "no icon"), not an error (measured 2026-07-17). The
Office/32x32/set is missing many common names (document,video,contact,navigate,flag,code,spotlight,billboardall render blank). The reliable, tenant-confirmed set isSXA/16x16/(used by OOTB SXA renderings):promo,rich-text,image,video,gallery,navigation,link,link-list,title,page-content,page-list,pagination,breadcrumb,playlist,media-link,file-list. Harvest the valid palette by reading__Iconoff OOTB renderings under/sitecore/layout/Renderings/Feature/Experience Accelerator/*, then map to those (or a confirmedOffice/name). Renderings underFeature/Experience Accelerator/may prefer theSXA_MDIset.
Head-app pairing (to actually render)
The Sitecore-side clone makes the component available + authorable in Pages. For it to render (not show a MissingComponent box), pair it head-app-side: duplicate the source's .tsx → <Name>.tsx, register in .sitecore/component-map.ts (or .client.ts), deploy. See content-sdk-website-build-flow (per-component port) + content-sdk-app-router-component-registration.
Never clone Foundation/JavaScript Services/HostedJsonRendering for a code component. The CM ships it (base Json Rendering, a ComponentRef field); a ComponentRef value diverts the rendering to the beta atoms runtime (content-sdk-app-router-atoms).
Related
sitecoreai-auth— the client-credentials token.sitecoreai-graphql-schemas— Authoring+Management schema (createItem/copyItem/updateItem/deleteItem, ItemQueryInput).content-sdk-website-build-flow— the per-component build/port loop this plugs into.content-sdk-icon-chooser— pick + set the__Iconon every created rendering / template.- Sitecore docs: "Copy and customize a component" (SitecoreAI), "Creating New Components" (Sitecore Accelerate — clone Promo/PageContent).
Content SDK — Debug Layout Probe
Inspecting what SitecoreAI actually delivers to your head app is harder than it should be: the layout response is opaque JSON, the SDL only types LayoutData { item: Item }, and Edge caches changes for ~30 s after publish. This skill installs three small, reusable pieces that turn the head app into a diagnostic surface.
When to use
- A Sitecore component renders empty / wrong / nothing and you need to see the raw payload.
- A new content resolver is on the rendering and you don't know what shape
fieldswill be (array? object? nested data?). - You suspect Edge cache is hiding recent author changes.
- You want to verify dataSource resolution, FieldNames variant selection, or rendering-parameter values without checking the CMS.
- You're learning a Sitecore pattern (content resolver, integrated GraphQL, navigation) and want a fast feedback loop.
How to perform
Three pieces, in order:
1. Temporary /api/layout-debug route
Create src/app/api/layout-debug/route.ts:
import { NextResponse } from 'next/server';
import client from 'src/lib/sitecore-client';
export async function GET(request: Request) {
const { searchParams } = new URL(request.url);
const site = searchParams.get('site') ?? 'training';
const locale = searchParams.get('locale') ?? 'en';
const rawPath = searchParams.get('path') ?? '/';
const pathSegments =
rawPath === '/' || rawPath === '' ? [] : rawPath.split('/').filter(Boolean);
try {
const page = await client.getPage(pathSegments, { site, locale });
return NextResponse.json({ request: { site, locale, path: rawPath, pathSegments }, result: page });
} catch (err) {
return NextResponse.json(
{ request: { site, locale, path: rawPath, pathSegments }, error: err instanceof Error ? { name: err.name, message: err.message } : String(err) },
{ status: 500 }
);
}
}
Hit it with curl -s "http://localhost:3000/api/layout-debug?site=<site>&locale=<locale>&path=<route>" | python3 -m json.tool. Returns the raw LayoutServiceData the SDK pulled from Edge.
2. Reusable ResolverProbe component (src/ui/resolver-probe.tsx)
Pretty-prints fields, params, and rendering as JSON inside a card. Drop it in any new component that receives an unknown payload:
export const Default = (props) => (
<ResolverProbe component="My Mystery Component" {...props} />
);
The probe reports the payload's kind (array vs object vs primitive) so you can immediately classify the shape.
3. InstrumentedFrame wrapper
A thin caption strip above the rendered component showing componentName · variant · pattern · dataSource. Color-coded left rail per resolver pattern (accent=standard, ok=all-fields, warn=integrated-graphql, ink=content-resolver). Makes the four delivery patterns visually distinct on a single page.
Hard Rules
- The
layout-debugroute usesclient.getPage()which hits Edge Delivery. Author changes need a publish + ~30 s before they appear here. If a parameter change has "no effect," publish first and wait — don't change more things blindly. - For unpublished state, use
client.getPreview(searchParams)insidedraftMode()instead ofgetPage. Add a?mode=previewflag to the route if needed. Preview bypasses Edge. - Always wrap unknown components in
ResolverProbebefore writing a real implementation. Discover the payload shape from the live response, not from prose docs. - For new content resolvers, scaffold the dummy first, add to a page, publish, capture the JSON, THEN write the real component. The reverse loop (assume shape → write component → debug) costs 5× as much time.
- Remove or gate
/api/layout-debugbefore production deploy. It leaks the layout payload (incl. internal item IDs). Gate byprocess.env.NODE_ENV !== 'production'or delete before merge. tone="content-resolver"on InstrumentedFrame is the right default for any rendering whose payload shape isn't yet known — it visually flags "needs probing."
Stop Conditions
- Stop and capture the layout response as a fixture in
tests/fixtures/graphql/<rendering>.json(with provenance comment) once the shape is confirmed, so future tests don't depend on a live tenant. - Do not assume
fieldsis always an object. Some resolvers return arrays (Navigation, ChildrenContentResolver). Some return nested{ data: { datasource: ... } }(Integrated GraphQL). The probe tells you which. - Do not ship the ResolverProbe to production for a known-shape component. Replace with the real implementation once you know the shape; keep the probe pattern only for genuinely-unknown ones.
Verification
- Hitting the route should return JSON with
result.layout.sitecore.route.placeholderspopulated. - The InstrumentedFrame caption should match the layout response's
componentName/dataSourceexactly — if it doesn't, the wrong component is registered for that name. - A 500 from the route with
Edge fetch failedusually means Edge context ID is wrong in.env.local; checkSITECORE_EDGE_CONTEXT_ID.
Related
content-sdk-resolver-patterns— the catalog of payload shapes the probe will reveal.content-sdk-playground-pattern— the playground that owns this debug toolkit by default.sitecoreai-cli-cloud-workflow— pulling local serialized YAML lets you cross-check resolver behavior against authored state.
References
Content SDK — Feature Planner (feature → Sitecore blueprint)
A feature ask ("team page with filterable cards", "regional promo banner", "FAQ accordion") is cheap to build and expensive to build wrong. The costly defects on this stack all render correctly: a component nobody can edit, a datasource written into another site's tree, a list whose rows an author cannot add, a query that degrades silently on Edge. Each comes from a decision made, or skipped, before the first file. This skill makes those decisions explicit, in a fixed order, and writes them down as a one-page blueprint.
It plans; it does not build. Every step names the specialist skill that owns the procedure. Load that skill when the step is executed, not while planning, unless a decision depends on its detail.
When to use
- A feature request must become templates, renderings, datasources and head-app files.
- Before cloning a rendering, adding a component or extending a content model.
- When reviewing someone else's plan for a Sitecore feature ("did they decide authorability?").
Not for: writing the code (use the skills named per step), early idea exploration, or the architecture stage of a delivery pipeline that already owns ADRs and a blueprint (feed it this skill's decision order instead of running both).
Step 0: inventory what exists
Reuse beats creation. Before deciding anything, list the site's real component palette and content model: renderings, their datasource templates, Headless Variants, list containers, the /Data folders. A new presentation of an existing component is usually a skin or a variant, not a new rendering.
→ sitecoreai-content-composition (inventory recipe), sitecoreai-graphql-schemas (template reads), content-sdk-debug-layout-probe (what a page actually delivers).
The decision sequence
Decide in this order; later steps depend on earlier answers. Record each as chosen option + one-line why in the blueprint (references/blueprint-template.md).
1. What kind of thing is it?
| If the value… | It is a… |
|---|---|
| is the page's own subject (article body, product facts) | page field on the page template, read from the context item |
| differs per placement, authored in Pages | component with a datasource |
| is shared by every page of the site (logo, social links, legal line) | site-level setting item, read server-side, or chrome in a Partial Design |
| belongs to the component, not the instance (aria-labels, "Show more", empty-state lines) | Sitecore Dictionary entry, with a literal code default |
| is computable from the CM (counts, "available now", option lists) | derived at render time, never authored |
The liveness test: copy containing remain, available, today, now, left cannot be authored text; derive it. A historical fact ("143 sold since 2011") can be authored.
→ content-sdk-app-router-dictionary-and-i18n (dictionary keys; Edge returns the key itself for an untranslated phrase, so treat value === key as missing).
2. Content model
Name every template, its fields with types, base templates, __Standard Values defaults, insert options and where datasources live.
- Scope: renderings and datasource templates are collection-scoped; Available Renderings, Headless Variants, Page / Partial Designs, Placeholder Settings and Styles are site-scoped. A second site in a collection reuses the model for free.
- Datasource Location must be site-relative (
query:$site/...). A hard GUID pins every future site to the first site's/Data: authors of site B silently write into site A. Nothing catches it; audit it in the plan. - Local datasources live in
<Page>/Data, never bare under the page. - Per-instance knobs (layout style, tone) go on the datasource template as Shared fields, not on a linked Parameters Template; a linked params template on a datasource-backed rendering can drop the whole route on Edge.
- Fields that must not differ per language: mark them Shared at creation.
→
content-sdk-create-component(templates, relinks),sitecoreai-localization(versioned vs shared).
3. Rendering
| Question | Owner |
|---|---|
New rendering, or clone an OOTB one (Promo, PageContent, Link List)? Default: clone a JSON rendering; a Controller rendering has no componentName. | content-sdk-create-component |
| A variant of an existing rendering (same component, different field arrangement) or a sibling with its own rendering? Cheapest first: skin → Headless Variant → new rendering. | content-sdk-variants-vs-siblings, content-sdk-app-router-component-variants |
Does it show repeating rows? Then it is a list component: container + element template, __Masters, a branch as Datasource Template, children-aware delivery. A Multilist is not a list (rows can be re-pointed, never added). | content-sdk-list-component |
| Is it a layout (columns, rows, a split or bento section) the author arranges? Cheapest first: grid params on ordinary components → Container + splitters → a custom slot component with presets → a fixed-layout component with no placeholders. | content-sdk-layout-composition |
| Is it navigation? Decide the data source first: derived from the tree vs an authored link list. | content-sdk-navigation-component, content-sdk-app-router-component-level-navigation |
| Does a live site already use the rendering you want to change? Fork, don't mutate. | (plan a new name-prefixed rendering) |
4. Data strategy
| Shape | Use when | Watch |
|---|---|---|
| Plain datasource fields | one item, flat fields | the default; cheapest |
| SXA content resolver (e.g. datasource children) | container + children | children come back in item-name order unless __Sortorder is set |
Integrated GraphQL (ComponentQuery) | nested or cross-item data, list rows | it replaces fields wholesale; request every rendered field with metadata; text as { value } (or { value jsonValue }), image/link as { jsonValue }; no orderBy on children; Edge has a silent depth budget and a default page size of 10 |
| Component-level fetch (route handler) | genuinely non-authored data: live feeds, search, lazy branches | an exception per field, never per component |
Then: Server or Client component? Server by default; Client only for interaction state, and pass SDK field objects through, not plain strings.
→ content-sdk-resolver-patterns, content-sdk-app-router-component-data-strategy, content-sdk-app-router-graphql-data-fetching, sitecoreai-edge-graphql-capture (query budget), content-sdk-app-router-route-handler-vs-server-action.
Multilist vs Integrated GraphQL for a list is a question for the user, not an architecture default: add-a-row ergonomics vs one fewer moving part. Ask it.
5. Authorability (the acceptance bar)
A component is done when an author can find every value and change it, not when it renders.
- Every authored, human-readable value arrives on
fieldsand renders through an SDK field component (Text,RichText,Image,Link). - Empty fields stay selectable while editing: guard with
(isEditing || hasValue), never unmount on empty; setrenderChildrenWhenEmptyon aLinkthat wraps children (its default isfalse). - A component that swaps fields on runtime state renders all of them while editing.
- A value that legitimately comes from elsewhere names its source in the rendering's description; a rendering never carries a Datasource Template it ignores.
→
content-sdk-field-usage-image-link-text,content-sdk-app-router-editing-safe-rendering,content-sdk-component-naming-traps(map key must equalcomponentName).
6. Cross-cutting impact
Answer each with "none" or a named consequence. Silence is not "none".
| Concern | Question | Owner |
|---|---|---|
| i18n | Which fields are versioned, which Shared? New dictionary keys? Per-language routes? | sitecoreai-localization, content-sdk-app-router-dictionary-and-i18n |
| Personalization / A-B | Will marketers vary it? Then it must be a component with a datasource (variants swap datasources or hide components). | sitecoreai-personalization, content-sdk-personalization |
| Search | Indexed? Which fields searchable / facetable? Reference fields are not indexed. | sitecoreai-search-sources, content-sdk-search |
| Analytics + consent | New events? Gated by consent category? | content-sdk-analytics-events, content-sdk-tracking-consent |
| Caching / freshness | Which revalidation tags must a publish hit? Does the Edge webhook cover it? | content-sdk-app-router-cache-components-and-osr |
| SEO | New routes in the sitemap? Metadata fields? robots impact? | content-sdk-app-router-sitemap-robots |
| Multisite | Reused on another site? Datasource Location site-relative? Per-site <X> Folder needed? | content-sdk-app-router-multisite-management |
| URLs | Does code build path segments from item names? Live Edge indexes only the slugified path. | (assert on live, step 7) |
7. Delivery
- Serialization: which module owns the new templates, renderings and site items; serialization grain is the collection, so a new site gets an include in the collection's module, never a second module on the same paths. →
sitecoreai-serialization,sitecoreai-cli-cloud-workflow. - Publish scope: templates, renderings, datasources, media, dictionary folder (a dictionary change needs the folder published with children).
- Preview ≠ live. Preview is the permissive runtime (resolves both URL forms, serves media without a publish, single-process caches). Name one assertion against live for every contract that can differ: route form, media, revalidation, variant selection (verify Headless Variants at Edge, never by a CM read-back).
→
content-sdk-website-build-flow(CM-then-Edge-then-deploy order),sitecoreai-publishing.
Output
Fill references/blueprint-template.md, one page. It is complete when every decision has an option and a why, every item and file to create is listed, each step names the skill to load, and the acceptance tests include "an author can find and change every value in Pages". Two worked examples: references/worked-examples.md. Patterns that look reasonable and fail silently: references/anti-patterns.md; check the finished blueprint against it.
Stop and ask
- The plan needs a change to a rendering a live site uses, and forking is not acceptable.
- A list's storage (Multilist vs child items via Integrated GraphQL) is undecided.
- "Everything is derived": a component with no authored value is a finding, not a design.
- A cross-cutting row cannot be answered from the ask.
Content SDK Field Usage
Use SDK field components to render Sitecore fields with proper validation and fallbacks. This concern is the same in App Router and Pages Router — the components, props, and guards below are identical. Only the way fields is delivered to the component differs by router, and that wiring belongs to the component-data-strategy skill (pointer in Hard Rules), not here.
When to use
- User asks how to render a title, body, image, or link from Sitecore.
- Task involves displaying content fields, fixing empty/broken images or links, or using RichText/Text/Image/Link components.
- User mentions "field," "Image," "Link," "Text," "RichText," or "field value."
How to perform
- Use SDK field components:
<Text field={fields?.title} />,<RichText field={fields?.content} />,<Image field={fields?.image} />,<Link field={fields?.link} />. Guard withfields?.when optional; use tag prop on Text when needed. Do not hardcode media or link URLs from Sitecore.
Hard Rules
- Prefer SDK field components over manual field value extraction:
<Text field={fields?.title} />,<RichText field={fields?.content} />,<Image field={fields?.image} />,<Link field={fields?.link} />. Use tag prop for Text when needed (e.g. tag="h1"). - Guard field existence, not value, for optional fields.
fields?.title(existence) is correct — it stopsundefinedbeing fed to a helper for a field absent from the datasource. But do not gate a helper on an empty value (e.g.{field?.value?.href && <Link/>}): that also hides the field in the editor, leaving the author nothing to click. The SDK helpers already render an editable empty-field placeholder in edit mode andnullwhen empty + published — so render the helper and let it decide. When you must conditionally render a wrapper, admit edit mode:{fields?.x && (isEditing || hasValue) && <Helper/>}. For the full edit-mode contract (empty-field visibility, inert forms, field-backed labels) seecontent-sdk-app-router-editing-safe-rendering/content-sdk-pages-router-editing-safe-rendering→ "Authoring-safe components." - Do not hardcode image or link URLs when the data comes from Sitecore; use the field components or helpers that resolve media/URLs.
- Never default an empty link href to
'#'(href: link?.value?.href || '#'). On a published page it produces a live, dead anchor, and a test can end up asserting the bug as intended. Passundefinedso the attribute is omitted, or let<Link>render nothing for an empty field. AssertgetAttribute('href')isnullon an empty Link field (one build swept six instances, 2026-09-28). - Wrapping
<Link>text in an element is authoring-safe:<Link field={f}><span>{f.value.text}</span></Link>.withFieldMetadatawraps the whole<a>in the field chrome, whatever its children, so the field stays inline-editable, and an empty link still renders nothing unlessrenderChildrenWhenEmptyis set.showLinkTextWithChildrenPresentdoes not do this: it renders the text as a sibling of the children, for an icon next to the text. - Match the source markup per link class, not globally. When porting an existing site, a shared CTA helper must reproduce each class of link as the source writes it. One build had
<a><span>Text</span></a>on one hero widget and bare<a>Text</a>on every other CTA. Wrapping every call site to fix the one broke all the others (2026-09-29). Make the wrap an opt-in prop. - Follow the app's import pattern (e.g. from lib or components).
- Where
fieldscomes from is router-specific and out of scope here: App Router resolves it fromgetPage(and may pass it as serializable props from a Server Component to a Client Component); Pages Router resolves it viagetComponentDatafrom the[[...path]].tsxcatch-all. For that wiring usecontent-sdk-app-router-component-data-strategyorcontent-sdk-pages-router-component-data-strategy.
Stop Conditions
- Stop if the field structure (name or type) is unknown; suggest checking the layout/data shape or asking the user.
- Do not assume field names (e.g. "title") without confirmation when the template might use different names.
- Do not commit or log raw field values that might contain PII or secrets.
References
Sitecore Icon Chooser
Picks the best matching icon from the Sitecore office/16x16/ icon set for a rendering/component based on its name and purpose, then applies it via the Authoring GraphQL updateItem mutation.
When to load
- Scaffolding a new rendering item in Sitecore (right after
createItem) - As a mandatory step of the component-creation Definition-of-Done (
content-sdk-create-component§ Icons) — every new rendering + datasource + folder + params template gets an__Icon - Auditing renderings that have blank or wrong icons
- Bulk-assigning icons after a
dotnet sitecore ser push - Any time you need to set the
__Iconstandard field on a rendering
0. PROBE BEFORE YOU WRITE — the catalog is a shortlist, not a guarantee
An icon in this catalog can still 404 on your tenant, and nothing downstream will tell you.
A dead __Icon is not an error: the mutation succeeds, the field reads back exactly what you
wrote, serialization is clean, and audit-sitecore-schema.mjs reports the item as icon-clean —
because that audit is read-only and unauthenticated, so it can only check the field is
non-empty. The only symptom is a blank/default document icon in the content tree, which
nobody sees until an author opens it.
SitecoreAI ships a reduced icon set. On a live sweep against one SitecoreAI tenant on 2026-08-08, 32 of 86 icons were dead — every one a plausible, correctly-spelled name straight from the Sitecore Icon Search tool. Those 32 were replaced with probed alternatives, and the resulting catalog was re-probed in full on 2026-08-28: all 102 paths resolve. But your tenant's set may differ again: the evidence is from one tenant, and whether the reduction is uniform across SitecoreAI is unverified.
So, every time, before updateItem:
curl -sL -o /dev/null -w "%{http_code} %{content_type}\n" \
-H "Authorization: Bearer $TOKEN" \
"https://<cm-host>/~/icon/office/16x16/<name>.png"
# 200 image/png = real. 404 text/html = dead, pick another.
Or run the bundled script, which asserts both § 0a controls first and exits 2 rather than judge anything when either misbehaves:
SITECORE_CM_TOKEN=… node scripts/probe-icon.mjs --host https://<cm-host> office/16x16/star.png office/16x16/tag.png
# exit 0 all resolve · 1 some dead · 2 harness untrusted (controls failed)
# --apply <itemId> additionally sets __Icon via § 5c and asserts the read-back
0a. Probe BOTH controls — a known-bad AND a known-good
Assert two controls in the same run, and abort the sweep if either misbehaves:
| Control | Expected | Catches |
|---|---|---|
office/16x16/__control_not_real__.png | 404 + text/html | An auth redirect being read as success — an unauthenticated GET returns 302→200 for every path |
office/16x16/window.png | 200 + image/png | An expired or unscoped token, which makes every real icon look dead |
The known-good control is the half that is usually missing, and it is the one that bites.
Measured 2026-08-28 on one shared CM: a sweep reported 38 of 38 icons dead, including
star, tag, table and document_text — all of which are real. The token in
.sitecore/user.json had expired two days earlier, so every request followed a redirect to the
Cloud Portal login page and came back 200 text/html, 2813 bytes. The check status === 200 && content-type startsWith('image/') did exactly what it was written to do and still produced a
100%-wrong answer, because a uniform failure is indistinguishable from a uniform absence without
a positive control. Re-run with a fresh token: 10 dead, 28 fine.
A sweep where everything fails is a claim about your credentials, not about the tenant. Treat a 0%-pass rate as a broken harness until a known-good control says otherwise.
The credential store is shared mutable state. .sitecore/user.json is rewritten by any
dotnet sitecore command in any concurrent session, and it holds several endpoints (default,
cm, xmCloud, per-org) that do not all carry a token or point at the same host — picking
Object.values(endpoints)[0] can silently aim your probe at the Deploy API. Observed on the same
day: the file changed underneath a running investigation, so two sweeps minutes apart used
different credentials. Re-assert the controls on every run, not once per session.
Prefer a non-expiring credential. The Sitecore CLI's accessToken in .sitecore/user.json
lasts ~24 h and needs a human at a browser; a client-credentials token from the CM automation
client authorizes /~/icon/ just as well and mints unattended. Assert the token's own
tenant_name claim, so the host and the credential cannot disagree.
There is no substitution rule to infer from. Business/32x32/key.png is dead where
Office/32x32/key.png serves — so the folder can be the problem. But document.png and
flag.png resolve under no folder, at either size, in any casing — so the name can
be the problem too. Do not reason from stock Sitecore, from another tenant, or from training
data. Probe.
Reference implementation: a CM-side verify-icons.mjs (the same shape as scripts/probe-icon.mjs, run over every module) sweeps every
__Icon in a serialized module and exits 1 on any that does not resolve
(--brand <slug> / --all / --probe <icon>). It mints its own client-credentials token and
asserts both controls from § 0a before reporting — it did neither until 2026-08-28, which is how
it produced the 38-of-38 false sweep described above.
1. Icon path format
The Sitecore __Icon standard field holds a relative path from the icon server root:
<folder>/<size>/<name>.<ext>
Primary set (this skill): office/16x16/<name>.png
The icon search tool shows paths as ~/-/icon/office/16x16/<name>.png — strip the ~/-/icon/ prefix for the field value.
| Tool path (URL) | __Icon field value |
|---|---|
~/-/icon/office/16x16/document_text.png | office/16x16/document_text.png |
~/-/icon/office/16x16/navigate_right.png | office/16x16/navigate_right.png |
SXA_MDI set: SXA_MDI/16x16/<name>.png — used by SXA-native renderings (see § 4).
⚠️ Paths are case-sensitive. office/16x16/Shopping_Cart.png fails if the file is named shopping_cart.png. Use the exact casing from the catalog in references/icon-catalog.md § 3/§ 8.
⚠️ A path is not a name. Many icons are <word>_<qualifier>.png and the bare <word>.png does
not exist — document_text yes / document no, find_text yes / find no. Copy the value; do
not compose it. Full list: § 3a.
2. Decision algorithm
Given: renderingName (required), description (optional)
Step 1 — tokenize renderingName
Split on: PascalCase, camelCase, hyphens, underscores, spaces
Lowercase all tokens
Examples:
"DesignManifesto" → ["design", "manifesto"]
"NavigationBar" → ["navigation", "bar"]
"HeroImageBanner" → ["hero", "image", "banner"]
"ContactDetailsFolder"→ ["contact", "details", "folder"]
"ProductCardItem" → ["product", "card", "item"]
Step 2 — score tokens against keyword table (`references/icon-catalog.md` § 3)
For each token, look up the keyword column
Accumulate score per category (1 point per keyword match)
Step 3 — pick winner
Highest-scoring category → use its Primary icon
Tie → use whichever has the higher-priority token (navigation > container)
No match → use `office/16x16/window.png` (generic container)
Step 4 — folder-type override
If renderingName ends in "Folder", "Container", "Group" → `office/16x16/folder.png`
If renderingName ends in "Item" only (no other category match) → `office/16x16/document_text.png`
Step 5 — SXA override (§ 4)
If rendering is under /sitecore/layout/Renderings/Feature/Experience Accelerator/
AND an SXA_MDI icon exists for this component type → prefer SXA_MDI
3. Semantic catalog
The keyword → path table per semantic category (navigation, content, media, layout, hero, cards, search, forms, social, people, e-commerce, blog, charts, map, settings, email, travel) lives in references/icon-catalog.md § 3. Read it when step 2 of the decision algorithm needs a category lookup; every path in it was probed green on 2026-08-28, but § 0 still applies — probe before you write.
3a. ⛔ Dead lookalikes — names that are NOT paths
This is the single most productive defect in this skill's history. The § 8 table has two columns — a semantic name on the left and the actual path on the right — and for many entries they differ. Reading the left column as a filename produces a plausible, correctly-spelled, completely dead icon path.
Measured on one shared CM 2026-08-28: one brand module carried 75 items across 10 dead icon values, and 7 of the 10 are exactly this mistake. Every other brand in the same CM was clean apart from one other brand (9 items, 2 values).
Every name in this table 404s. Never write one as an __Icon value:
| ⛔ Dead name you will reach for | ✅ The path that actually exists | items hit (one brand) |
|---|---|---|
office/16x16/document.png | office/16x16/document_text.png | 23 |
office/16x16/navigate.png | office/16x16/navigate_right.png | 16 |
office/16x16/flag.png | office/16x16/bookmark.png (or megaphone.png for campaigns) | 9 |
office/16x16/find.png | office/16x16/find_text.png | 8 |
office/16x16/image.png | office/16x16/photo_landscape.png | 7 |
office/16x16/settings.png | office/16x16/gearwheel.png | 2 |
office/16x16/database.png | office/16x16/server.png | 2 |
office/16x16/table_list.png | office/16x16/table.png / text_align_left.png | 3 |
office/16x16/document_check.png | office/16x16/document_selection.png / clipboard.png | 3 |
office/16x16/weather_sunny.png | office/16x16/sun.png | 2 |
office/16x16/palette.png | office/16x16/photo_landscape.png | 7 |
office/16x16/color_swatch.png | office/16x16/photo_landscape.png | 2 |
Also confirmed dead on the same tenant, and all tempting: list, list_bullets, checklist,
search, nav, form, picture, photo, gallery, images, view, magnifier, plane,
flight, luggage, route, direction, play, cog, sliders, check*, checkmark,
accept, apply, translate, language, weather, weather_cloudy, rain, snow, wind,
umbrella, speaker, bullhorn, binoculars, image_landscape.
* check.png does resolve; checkmark/accept/apply do not. This is the point — there
is no rule, only the probe.
The guard: the value you write must be copied from the right-hand column of § 3 or § 8, never retyped from the component's own vocabulary. Then probe it (§ 0).
4. SXA_MDI icon set (SXA-native renderings only)
For renderings under /sitecore/layout/Renderings/Feature/Experience Accelerator/, prefer SXA_MDI icons for visual consistency with SXA's own content tree.
| SXA rendering family | Icon path |
|---|---|
| Promo | SXA_MDI/16x16/Promo.png |
| Navigation | SXA_MDI/16x16/Navigation.png |
| Rich Text | SXA_MDI/16x16/RichText.png |
| Image | SXA_MDI/16x16/Image.png |
| Carousel | SXA_MDI/16x16/Carousel.png |
| Page Content | SXA_MDI/16x16/PageContent.png |
| Container | SXA_MDI/16x16/Container.png |
| Search Box | SXA_MDI/16x16/SearchBox.png |
| Search Results | SXA_MDI/16x16/SearchResults.png |
| Page List | SXA_MDI/16x16/PageList.png |
| Title | SXA_MDI/16x16/Title.png |
For custom renderings in non-SXA projects, always use the office/16x16/ set.
5. GraphQL recipes
The four copy-ready Authoring GraphQL recipes — find a rendering by path (5a), browse a folder for a bulk audit (5b), update one icon (5c), batch-update (5d) — are in references/graphql-recipes.md. § 0 (probe both controls) still gates every write.
6. Complete worked example
Goal: Assign meaningful icons to all custom renderings under /sitecore/layout/Renderings/Project/acme/.
Step 1 — Browse renderings:
query {
item(where: { path: "/sitecore/layout/Renderings/Project/acme", language: "en" }) {
children {
nodes {
itemId(format: D)
name
field(name: "__Icon") { value }
template { name }
}
}
}
}
Step 2 — Apply the decision algorithm to each rendering:
| Rendering name | Tokens | Matched category | Chosen icon |
|---|---|---|---|
| DesignManifesto | design, manifesto | Content (design+manifest) | office/16x16/document_text.png |
| ContactDetailItem | contact, detail, item | People/Contact (contact wins) | office/16x16/telephone.png |
| ContactDetailsFolder | contact, details, folder | Folder override (ends in Folder) | office/16x16/folder.png |
| ContactForm | contact, form | Forms (form wins over contact) | office/16x16/checkbox_group.png |
| DestinationCard | destination, card | Map/Location (destination wins) | office/16x16/map.png |
| DestinationsGridFolder | destinations, grid, folder | Folder override | office/16x16/folder.png |
| ExperienceItem | experience, item | Navigation (experience → journey) | office/16x16/navigate_right.png |
| ExperienceShowcase | experience, showcase | Hero/Promo (showcase → spotlight) | office/16x16/sun.png |
Step 3 — Fire batch mutation:
mutation {
r1: updateItem(input: { itemId: "aaa-guid", fields: [{ name: "__Icon", value: "office/16x16/document_text.png" }] }) {
item { name field(name: "__Icon") { value } }
}
r2: updateItem(input: { itemId: "bbb-guid", fields: [{ name: "__Icon", value: "office/16x16/telephone.png" }] }) {
item { name field(name: "__Icon") { value } }
}
r3: updateItem(input: { itemId: "ccc-guid", fields: [{ name: "__Icon", value: "office/16x16/folder.png" }] }) {
item { name field(name: "__Icon") { value } }
}
r4: updateItem(input: { itemId: "ddd-guid", fields: [{ name: "__Icon", value: "office/16x16/checkbox_group.png" }] }) {
item { name field(name: "__Icon") { value } }
}
r5: updateItem(input: { itemId: "eee-guid", fields: [{ name: "__Icon", value: "office/16x16/map.png" }] }) {
item { name field(name: "__Icon") { value } }
}
}
Step 4 — Verify: Re-run the Browse query (Step 1) and confirm all field.value entries are populated. Visually confirm in Sitecore Content Editor (requires page reload).
7. Pitfalls
| Pitfall | What happens | Fix |
|---|---|---|
| Writing the semantic NAME as the path | The highest-volume failure. office/16x16/document.png, .../image.png, .../find.png, .../navigate.png are all plausible, all spelled right, all dead. One brand shipped 75 blank items across 10 values this way; 7 of the 10 were § 8 left-column keys used as filenames | Copy the middle column of § 3/§ 8 verbatim. Never compose a path from the component's vocabulary. Blocklist: § 3a |
| Trusting the catalog without probing | updateItem succeeds, the field reads back correctly, serialization is clean, the schema audit reports the item icon-clean — and the tree shows a blank default icon. Silent until an author opens it | Probe every icon before writing it (§ 0). 32 of this catalog's 86 icons were dead on a live SitecoreAI tenant |
| Probing without a known-bad control | An unauthenticated GET returns 302 for every path, real or not, so "not 404" reads as success and every icon looks alive | Send the bearer token, follow redirects, and assert 200 and content-type: image/*. Probe a deliberately fake name in the same run |
| Probing without a known-GOOD control | An expired token redirects every request to the login page, which answers 200 text/html. Every real icon reports dead and you "discover" a catastrophe that isn't there — measured 2026-08-28 as 38 of 38 false positives | Assert office/16x16/window.png returns 200 image/png before believing any result. A 0%-pass sweep is a credential problem (§ 0a) |
Sweeping with the CLI's user.json token | It expires in ~24 h, so the sweep silently degrades into the false-positive case above overnight | Mint a client-credentials token instead (clientFor('<org>')), which also asserts the tenant claim |
| Assuming a folder or size substitution | Office/32x32/key.png serves where Business/32x32/key.png 404s, so folder matters — but document.png and flag.png are absent under every folder and size, so name matters too | No inference rule exists. Probe each candidate |
| Wrong case in icon path | Icon not found → blank/broken icon in CM | Use exact casing from § 9 catalog |
Including ~/-/icon/ prefix | Field stores the full URL, resolves to double-path | Strip prefix; use office/16x16/person.png only |
| Updating a read-only or locked item | GraphQL returns error | Unlock item first via Content Editor or unlockItem mutation |
Setting __Icon on a rendering item inside a folder template | Works but the folder's icon also changes | If you only want the rendering icon, target the rendering item's GUID specifically |
| Empty string value | Falls back to template default icon — may look fine but field.value = "" | Set to explicit icon path rather than clearing |
| SXA_MDI icon on a non-SXA rendering | May not resolve visually | Only use SXA_MDI for SXA renderings; use office/ for custom ones |
8. Icon catalog quick reference
The flat 102-path quick reference (plus the 2026-08-28 additions) is in references/icon-catalog.md § 8. Copy paths from its middle column verbatim — never compose one from the component's vocabulary (§ 3a).
Content SDK: layout composition
Authors build page layout in Pages by nesting structure renderings (Container, Column Splitter, Row Splitter) and by sizing components with grid parameters. The CM already ships all of it. The head app has to supply three things, and each fails silently when missing: the React components, the right placeholder names, and CSS for grid classes that arrive from the CM at runtime.
When to use
- A page or design needs columns, rows, a sidebar, a split hero, a bento grid, or nested sections an author can rearrange.
- Porting or scaffolding a head app that authors will compose in Pages (the scaffold ships none of the structure components).
- Symptoms: "Container — missing React implementation", columns stacking like rows, an invisible container, a splitter that makes everything vanish, children that never render inside a column, the class
undefinedin the DOM, a grid size picked in Pages with no effect.
Not for: several looks of one component (content-sdk-variants-vs-siblings), repeating rows of one content type (content-sdk-list-component), header and footer chrome via Partial Designs (content-sdk-website-build-flow).
The model in four facts
- Placeholder keys. Edge delivers
container-{*},column-N-{*},row-N-{*}and puts the instance id inparams.DynamicPlaceholderId. Name the child placeholdercolumn-${n}-${DynamicPlaceholderId}: the SDK matches it against^column-N-\d+$. The literalcolumn-N-{*}also works. A fixed name such ascolumn-1finds nothing, and nothing errors. - Active slots. Edge emits all eight column or row keys every time.
EnabledPlaceholders(1,2, sometimes unsorted:1,3,2,4) is the only record of which are in use. - Grid classes come from the site's grid definition (Bootstrap 5 by default), stored as one option GUID per breakpoint and delivered by Edge as space-joined class names:
ColumnWidth1: "col-12 col-md-8". They are runtime strings, so a Tailwind build never generates CSS for them. params.stylesis computed by the SDK from GridParameters + Styles, and is absent when both are empty. Interpolating it printsundefined.
Detail and evidence: references/standard-structure.md (renderings, params templates, placeholder settings, Edge shape, SDK resolution, writing a layout programmatically), references/grid-and-css.md (grid definitions, the CSS fix, the editing surface) and references/policy-and-fit.md (policy, responsive matrix, fit tiers, container queries).
The layout policy
At every nesting level exactly one mechanism decides widths. Full table, matrix and measurements: references/policy-and-fit.md.
- Container owns the section (one per section, directly in
headless-main). Column Splitter owns the horizontal split viaColumnWidthN. Component grid size (GridParameters) is for uniform peers straight in a Container. Row Splitter only for styled row bands. Slot component for brand compositions picked as a preset. A fixed-layout component when the arrangement is not the author's to change. - Depth: Container → (Column Splitter | slot component) → components; one extra splitter level is the single exception. A row holds one thing. Inside a column or slot a component is never sized. 12 is often right: a component that lays out its own items belongs at 12.
- Responsive: Mobile is always 12, set first (Pages gives a new column
col-6at Mobile). The narrowest column stacks first, never below ~240 px. No orphans. Standard layouts:
| Desktop | Tablet | Mobile | Classes |
|---|---|---|---|
| 12 | 12 | 12 | col-12 |
| 6/6 | 6/6 | 12 | col-12 col-md-6 |
| 8/4 · 4/8 | 8/4 | 12 | col-12 col-md-8 / col-12 col-md-4 |
| 9/3 · 3/9 | 12 | 12 | col-12 col-lg-9 / col-12 col-lg-3 |
| 4/4/4 | 12 | 12 | col-12 col-lg-4 |
| 3/3/3/3 | 6/6 | 12 | col-12 col-md-6 col-lg-3 |
- Component fit: a column placeholder does not know its width, so fit belongs to the component. Each head app keeps
src/lib/layout/component-fit.ts(templateassets/component-fit.ts): chrome (Partial Designs only), section (top-level Container at 12 only), wide (≥ 6/12 wherever it sits side by side), flexible (any column ≥ 240 px). It is a living list: when a case does not fit, re-tier the component or adapt it with container queries so it responds to its own width, not the viewport (policy-and-fit.md§ 4).
Procedure: structure components
- Copy the helper:
assets/layout-params.ts→src/lib/layout/layout-params.ts. Never place it undersrc/components/, where generate-map registers every file as a rendering (content-sdk-component-naming-traps). - Copy the components from
assets/components/:Container.tsx,ColumnSplitter.tsx,RowSplitter.tsx, each intosrc/components/<Name>/<Name>.tsx. The file name must equal thecomponentName. They are upstream's markup with the defects fixed (noundefinedclass,EnabledPlaceholdersorder with a fallback, a placeholder name that survives a non-numeric id). KeepPartialDesignDynamicPlaceholderfrom the scaffold. - Add grid CSS:
@importassets/bootstrap5-grid.cssat the top ofsrc/app/globals.css, right after@import "tailwindcss". It is plain CSS (the build cannot purge it), scoped to the rows the structure components emit, and styles empty drop zones in Pages. Then grep the app's own CSS for bare.row,.container,.col-Nrules and scope or rename them: an unlayered app rule beats the layered grid. Another grid definition: read its classes first (references/grid-and-css.md§ 1). - Make ordinary components honour grid params: add a
paramsprop where a component takes onlyfields, and putclassName={cx('component <own-classes>', styleClasses(params))}on its root element. - Nested placeholders always use
AppPlaceholderwith the server map (import componentMap from '.sitecore/component-map'). The barePlaceholderresolves the client map in App Router, and every child renders "unknown component". npm run sitecore-tools:generate-map; check the keysContainer,ColumnSplitterandRowSplitterare present, and update any component-map key snapshot test the app keeps.- Write the fit file (
assets/component-fit.ts→src/lib/layout/component-fit.ts+component-fit.json), every rendering with a tier and a reason. - CM side: confirm the three JSS Page Structure renderings are in the site's Available Renderings. They usually are, but a site can repurpose the group.
- Run
node scripts/check-layout-wiring.mjs --app <head-app>, then Verification below.
Procedure: custom slot component
Follow references/custom-layout-component.md:
- Decide the slot prefix, the slot count and the presets.
- Create the items: a params template on
BaseRenderingParameters+IDynamicPlaceholder, one Placeholder Settings item per slot (<prefix>-N-{*}), and a Json Rendering withPlaceholdersandOtherProperties = IsRenderingsWithDynamicPlaceholders=true. Then Available Renderings, and Style items for the presets. Item mechanics:content-sdk-create-component. - Copy
assets/components/LayoutGrid.tsx+layout-grid.cssand adaptPREFIXandPRESETS. - Run the reference's § 6 probe on a throwaway page before the first real use. The CM wiring and delivery were field-tested; authoring a slot component in Pages has not been yet.
Traps
| Symptom | Cause | Fix |
|---|---|---|
| "Container — Content SDK component is missing React implementation" | The scaffold ships no structure components | Step 2 |
| Columns stack like rows; container invisible; dropping a splitter "deletes" the page | No CSS for the runtime grid classes, or it was purged | Step 3 |
| Children never render inside a column; console "Placeholder 'column-1' was not found" | A fixed placeholder name | slotName() |
| Children render as "Placeholder X contains unknown component" | Bare Placeholder, which uses the client map | AppPlaceholder + server map |
class="row component column-splitter undefined" | Raw ${params.styles} | styleClasses(params) |
| Eight columns render, six of them empty | Slots taken from rendering.placeholders | enabledSlots(params) |
| Author sets a width in Pages, nothing changes | The component ignores its params | Step 4 |
| The Column Splitter panel has no width control | Widths live on each column | Select the column, then Design → Layout → Size |
| A fresh two-column splitter stays side by side on phones | Pages gives a new column col-6 at Mobile | Set 12 at Mobile, override at a larger breakpoint |
An app's own .row band shifts or gets padded after adding the grid | An unscoped grid .row rule | The scoped bootstrap5-grid.css (0.2.0+) |
| Splitter rows turn into the app's own 100vw band | The app's unlayered .row rule wins | Scope the app rule (app-css-collision) |
| The page is 12 px wider than the viewport | Row negative margin with no padded parent | The grid's Container padding (0.2.0+) |
| A component overflows or breaks words in a narrow column | It sizes itself by the viewport | Re-tier it, or make it container-aware (policy-and-fit.md § 4) |
Pages on a local editing host gets 401 on /api/editing/config | .env.local secret is not the CM environment's editing secret | grid-and-css.md § 4 |
| A layout written through GraphQL renders nothing | Not Pages' delta form, or updateItem without version: 1 | standard-structure.md § 4a |
| Grid change not visible locally | Turbopack does not hot-reload globals.css | Stop the dev server, rm -rf .next, restart |
A Bootstrap 3 col-xs-* from migrated content | The source grid survived migration | The static grid aliases col-xs-* |
| Content vanishes after switching a preset | It sits in a slot the new preset does not render | Switch back, or render overflow slots while editing |
Verification
Static checks prove the wiring; only a rendered page proves the layout.
node scripts/check-layout-wiring.mjs --app <dir>: missing grid CSS, partial structure set, fixed keys, bare Placeholder, unguardedstylesand slots taken fromplaceholders(FAIL or WARN); components ignoring their params (WARN). Exit 1 on FAIL.--self-testruns its fixtures and a mutation sweep.node scripts/test-layout-params.mjs --self-test: the helper against param shapes captured from Edge.node scripts/lint-layout.mjs --site <s> --route </path> --env-file <app/.env.local> --fit <app>/src/lib/layout/component-fit.json(or--layout <edge-layout.json>): checks a delivered page against the policy (depth, one thing per row, unstyled Row Splitter, sized component in a column), the responsive rules (12 on Mobile, orphans, columns under 240 px) and the fit tiers (section in a column, wide below 6/12, chrome on a page). Point--env-fileat a PREVIEW context for unpublished pages; in Git Bash prefixMSYS_NO_PATHCONV=1. Run it after a page is composed, by an agent or an author.- One real page: a Container holding a two-column Column Splitter with a component in each column. Read its layout (
content-sdk-debug-layout-probe), then render it in a real browser at a mobile and a desktop width: the columns sit side by side atmdand stack below it. Jest masks every failure above, because a mocked layout never carries{*}keys or runtime classes. - In Pages edit mode: an empty column shows a full-width drop zone, and changing a column width or style refreshes live.
- After adapting a component: re-measure the pages that already use it at full width (element boxes before and after) before re-tiering it.
Sitecore List Components
The decision, first
Ask one question about every rendering: would an author ever want to add a row?
| Answer | Shape |
|---|---|
| No — a fixed set of the datasource's own fields | Single component. One datasource template. Done. |
| Yes — repeating rows: nav links, cards, stats, entries, panels, tabs | List component. Everything below applies. |
Get this wrong and the component still renders perfectly, passes every test, passes the authorability audit, and is un-editable in the way that matters: the author can change the rows that exist and cannot create one.
FOUR legs, and they fail independently — check all four. Measured on one brand, 2026-08-28, where four renderings displayed repeating rows (Header/NavLink, ServiceTrio/ServiceItem, SelectedWork/WorkEntry, StatBand/StatItem) and every one came out identically:
| Leg | What it buys | measured |
|---|---|---|
0. _HorizonDatasourceGrouping base template | the Items edit section in Page Builder — where an author can create a child of the right type | ❌ absent on all four |
1. __Masters on the container SV | insert options — which template a new child uses | ✅ correct on all four |
2. Datasource Template = a BRANCH | a new datasource ships with a row already in it | ❌ bare template |
| 3. children-aware delivery | the added child actually renders | ❌ Multilist on the container |
Leg 0 is the one an author notices, and it is the easiest to miss because the component is otherwise complete. Without it the insert options exist only in the Content Editor tree — which is not where authors work. _PublishingGroupingTemplate travels with it (11/11 and 6/6 on the two brands of that estate that carried it).
⚠️ Legs 0 and 1 are independent, not two names for one thing. Measured across one estate: one brand has 6 templates with Horizon and no __Masters; another has 2 with __Masters and no Horizon, and 9 with both. Do not infer one from the other, and do not assume that having one means the author can add a row.
Leg 1 passing is not evidence for the rest. All four of that brand's components shipped past 74 unit tests, a 7/7 authorability audit, four code reviews and a full test pass. It was found by a human opening Pages and looking for an add button.
This is an estate-wide gap, not one build's miss. _HorizonDatasourceGrouping appears on 11/34 and 6/37 templates of two brands, and on 0 of 64, 0 of 32, 0 of 44 and 0 for the other four — so four of six brands shipped with no list-editable component at all.
Why a Multilist is not a list component
A Multilist (or Treelist / Checklist) field on the parent datasource references items that already exist somewhere else. Consequences an author feels:
- Adding a row is two operations, in two places — create the item in the content tree, then come back and add it to the field. Miss the second and the item exists and renders nowhere.
- There is no "add" affordance in the component itself. The author must know where the items live.
- You do not control the ordering from the component — it is the field's order, edited in a picker.
A list component's rows are children of the datasource, so adding one is a single action in Pages, in place.
Multilist is still right when the referenced items are shared across components or pages (a global set of links, a shared taxonomy). Choose it deliberately, not by default.
The four deltas vs a single component
Read-confirmed against the OOTB SXA Link List on a live tenant, 2026-06-23.
0. Base templates on the CONTAINER — the leg that decides whether Pages shows anything
<container template> → __Base template =
Standard template | _PublishingGroupingTemplate | _HorizonDatasourceGrouping | _PerSiteStandardValues
| GUID | |
|---|---|
{D0F6BE14-2A2D-4C56-ACB5-80CAA573B8E2} | _HorizonDatasourceGrouping |
{8BA7DAC6-32ED-4378-BD9E-5DA5B0F9848D} | _PublishingGroupingTemplate |
_HorizonDatasourceGrouping is what gives Page Builder the "Items" edit section, through which an author creates a new child of the right type. Skip it and everything else can be correct while the author sees no way to add anything — because the affordance the other legs enable lives in the Content Editor tree, not in Pages.
✅ Confirmed in Page Builder, 2026-08-28. That brand's four containers had __Masters correct and no Horizon: no Items section. Adding _HorizonDatasourceGrouping + _PublishingGroupingTemplate to the container templates — changing nothing else — made the Items section appear, verified by a person in the canvas. This is a measurement, not an inference from the estate.
Put it on the container only. The element template is a row, not a grouping.
1. Two datasource templates
- A container — the list-level fields (
Title,Heading). - An element — one row's fields (e.g.
Link <General Link>).
The element has no __Standard Values in the OOTB pattern.
2. Insert options wire container → element
<container template>/__Standard Values → __Masters = <element template id>
__Masters decides which template a new child is created from. OOTB Link List's SV carries __Masters = {E24E0789-A058-48BF-ABB6-C69C0E60B6B7} (the Link template).
⚠️ This is not the same thing as leg 0 and does not substitute for it. An earlier version of this skill claimed __Masters "is what puts the add affordance in Pages" — that is wrong, or at best true only in the Content Editor. The estate disproves the conflation directly: one brand carries Horizon on six templates that have no __Masters at all.
3. The rendering’s Datasource Template points at a BRANCH, not a bare template
/sitecore/templates/Branches/Project/<Brand>/<Site>/<Component>
The branch's $name item uses the container template, also carries __Masters, and ships one default element (Link 1) — so a newly created datasource is a non-empty list rather than an empty box the author has to guess at.
Pointing at the bare container template instead gives the author an empty list on every new datasource.
4. Children-aware delivery
The rows are children, so the payload must carry them. The mechanisms are ranked. First check the list really is owned rows: content-sdk-collection-data-model decides that.
| Rank | Mechanism | Note |
|---|---|---|
| 1 | Integrated GraphQL (ComponentQuery) with every field as jsonValue | Expresses container fields and children in one query. Marketer-friendly, one write operation per row, and go-live is controlled by workflow. A new row reaches the page after the page is republished. Row fields edit inline and rows reorder in Pages (confirmed by hand 2026-11-04). |
| 2 | Component-level fetch | A server fetch in the head app. Pages freely and has no republish dependency, but carries no editing metadata: right for rows authored elsewhere, not for owned rows. |
| avoid | Children content resolver | Delivers Shape B { items: [...] } and nothing else, so the container's own fields (Heading) are lost. Sitecore documents content resolvers as not supported with Edge runtime publishing, with no filtering or paging, and nothing documents their output as editable. |
⚠️ ComponentQuery replaces the ENTIRE fields payload, taking inline-editing metadata with it for every field not selected as jsonValue (the authorability principle: a component is done when an author can find its content and change it, not when it renders). That is a reason to design the query to return everything the component renders — not a reason to ban the mechanism. A blanket "no ComponentQuery" rule pushes every list onto Multilist and produces the un-extendable shape above.
⚠️ A ComponentQuery list has two silent failure modes (measured 2026-09-26 → 28; the full budget table is in sitecoreai-edge-graphql-capture § 2b):
childrennested two levels deep inside aComponentQuerybreaks resolution. The rendering arrives withisContentResolved: falseand no error. Keep the query to one level ofchildren, and fetch deeper rows server-side withclient.getData.- A row past
children(first: N)is silently dropped.firstmust be strictly greater than the authored row count, or the row an author adds in Pages never reaches the page. Sizefirstto the real row count plus headroom, not a blanket 50, becausefirst:50alone can exceed Edge's complexity budget. Record each list's maximum authorable row count next to its query.
Build order
- Create the element template (row fields). Icon it.
- Create the container template (list-level fields). Icon it. Add
__Standard Values. - Set the container SV's
__Mastersto the element template id. ← the step that is easy to skip and defines the outcome - Create the branch under
/sitecore/templates/Branches/…,$nameon the container template, carrying__Mastersand one default element. - Point the rendering's
Datasource Templateat the branch. - Wire delivery: a
ComponentQuerywithjsonValuefields, the resolver cleared (ranking in leg 4). 6a. Set__Sortorderon every row you seed over Authoring GraphQL (steps of 100, in the intended order). Without it the rows come back alphabetically, not in creation order. One build shipped 5 nav sections and 63 links in the wrong order this way (2026-09-27). - Icons on every item and every
__Standard Values(content-sdk-icon-chooser).
Verify in the authoring UI, not in the tree
scripts/build-list-component.mjs does the mechanical half: verify --rendering <path> reads all four legs of an existing rendering off the live tenant (exit 1 on a missing leg), and build … prints the plan for a new one and only writes with --apply. It asserts the seven system GUIDs it relies on before judging anything, so a wrong host or token exits 2 rather than reporting a component as broken.
The tree looks correct at step 2. Open Pages, select the component, and confirm you can add a row. Nothing short of that proves __Masters and the branch are wired — no test, no schema audit and no authorability audit reaches this, because the component renders correctly either way.
Cross-references
content-sdk-create-component— base-template inheritance, template folder layout, thecopyItemrecipecontent-sdk-collection-data-model— whether a list is owned rows at all (derived views, curated references and large libraries are built differently)content-sdk-resolver-patterns— the 2×2 of resolvers and the two React-side payload shapescontent-sdk-icon-chooser— the__Iconstep in build order- The authorability principle — renders ≠ authorable: a component is done when an author can find its content and change it; this skill is the list-shaped case of it
Sitecore Navigation Components
The decision, first
Navigation looks like one problem and is two. The markup is nearly identical; the data source is not.
| Question | Shape |
|---|---|
| Should the nav change when someone adds a page? | Derived. Walk the content tree. |
| Is this a curated set of destinations an editor decides? | Authored. A list of link items. |
| One page, jumping to sections on it? | Authored, with anchor links. A derived nav has nothing to walk. |
Default to two renderings, not one with a mode switch. They share a presentation layer and
nothing else — different fields, different fetch, different failure modes, different editor
experience. One rendering that branches on a parameter has to satisfy both contracts at once, and
the trap in § "Do not fetch instead of fields" is exactly where that goes wrong.
Use one rendering with a Source rendering parameter only when you genuinely need an author to
flip an existing placement between modes without re-placing it. That is rarer than it sounds.
Both on one page is normal and correct — a derived site nav in the header, an authored section jump-bar under it. They are different renderings doing different jobs, not a duplication.
Derived navigation
Walks the tree from a root, to a bounded depth, through a filter.
rootPath is the SITE node, not Home
The single most common mistake. The site item and the home page are different items — point at the
site node and append /Home (or whichever child is the actual home) to get the level you mean.
Aiming at the site node and rendering its children gives you Home, Data, Media, Settings, i.e.
the site's plumbing in the navigation bar.
Bound the depth explicitly — Edge degrades SILENTLY
Sitecore Edge has a query depth budget, and exceeding it does not error. It returns a truncated result. A three-level nav built against a small tree works, ships, and then quietly loses its third level when the tree grows — with a green build, a 200, and no console warning.
So: state the depth as an explicit number (a rendering parameter or a field), never "walk all children". And when you test it, test against a tree deeper than the one you designed for — a nav that is correct on a 6-page site proves nothing about a 200-page one.
Filter deliberately
A Navigation Filters item (the SXA-shaped hook) or an explicit "show in navigation" checkbox on
the page template. Without one, every scaffolding page — Components Preview, test pages, staging
drafts — appears in the public nav the moment someone creates it. That is a content-authoring
accident waiting to happen, not a hypothetical.
The stock headless Navigation resolver: set its parameters, know its limits
Measured on SitecoreAI preview, 2026-10-29. With only the variant (FieldNames) on the placement, the
stock Navigation rendering returns level 1 below Home, no children, hidden pages included. Its
headless parameters template shows no navigation fields, yet the resolver reads SXA's Foundation
ones from the placement: Filter (a Navigation Filter item: Main / Sidebar / Breadcrumb Navigation),
LevelFrom and LevelTo (items under Navigation/Enums/Navigation Level), NavigationRoot,
Flattened, AddRoot. With a filter and levels set it drops filtered pages, nests Children and
marks the context page active; LevelFrom = LevelTo = 2 is a section menu of the current
level-1 ancestor. Every entry carries only Id, Href, NavigationTitle, Styles, Querystring.
Two things it cannot do: expand only the active trail (it returns the full level range for every
branch), and list an item whose template does not derive from _Navigable. A "link in the menu"
item (an external URL at a position in the tree) is skipped, and even on _Navigable it would get
its own URL, not the link. A menu that needs either keeps its own walk (component-level GraphQL),
reading the stock NavigationFilter so hiding a page still works the stock way.
Authored navigation
A curated list of links. This is a list component — an author must be able to add a row, not merely re-point rows that already exist.
Load content-sdk-list-component and follow it. The short version: a Multilist alone is the
wrong shape, because it only lets an author choose among items that already exist. You need a
container template that carries _HorizonDatasourceGrouping as a base template (that is what
gives Pages its Items section, i.e. the "add a link" affordance), an element template, insert
options via the container's __Standard Values.__Masters (which only decides which template a new
row uses), and a branch as the rendering's Datasource Template. The four legs fail
independently — an earlier version of this paragraph credited __Masters with the Pages affordance,
and that was wrong: a template can carry __Masters and still give an author no way to add a row.
In-page anchors (the one-pager case)
Each link item carries a General Link field whose linktype is anchor, with the target
section id as the anchor value. Two things to get right:
- The target
idmust exist in the rendered DOM. Assert it — an anchor pointing at a section that was renamed scrolls nowhere and returns HTTP 200 while doing it. - Never write
href={link?.value?.href || '/'}. A fail-open fallback turns a missing link into a silent dead link that every crawler and every smoke test reports as fine. Render nothing, or render the item unlinked, but do not invent a destination.
Do not fetch instead of fields — the trap that survives every gate
The authorability trap in its purest shape — a component that renders perfectly and cannot be edited — and navigation is where it bites hardest.
A derived nav is fetched, so it is tempting to fetch the authored one too — or to write one
component that fetches in both modes. ComponentQuery REPLACES the entire fields payload. A
component whose data arrives that way has no fields for the editor to click, so it renders
perfectly and cannot be edited in Pages. That is how a previous build shipped 17 of 21 renderings
un-editable past 704 tests, 88 e2e tests and four reviews.
The rule is narrow and worth stating precisely: "derive your TYPES from the SDK's .d.ts" is a
rule about typing what you fetch. It does not license fetching instead of fields.
- Authored nav: every link arrives on
fieldsand renders through an SDK field component. - Derived nav: the tree walk is a fetch, necessarily — but any authored chrome on the same
rendering (a heading, a CTA) still arrives on
fields. Do not let the fetch swallow the authorable parts.
Verify by opening the Pages canvas and clicking the thing. audit-component-authorability.mjs is a
floor: it cannot tell whether the fields a component renders are the right ones.
Checklist
- Decided derived vs authored from the data source, not from how it looks.
- Two renderings unless an author genuinely needs to flip modes in place.
- Derived:
rootPathresolves to the site node, with the home child appended. - Derived: depth is an explicit bound, and was tested against a deeper tree than designed for.
- Derived: a filter exists, so scaffolding pages cannot appear in the public nav.
- Authored: built as a list component (
content-sdk-list-component) — an author can ADD a row. - Anchors:
linktype: anchor, and every target id asserted present in the DOM. - No fail-open
|| '/'href anywhere. - Authored values arrive on
fields, not via aComponentQuerythat replaces the payload. - Opened Pages and edited one link by hand. The audit is a floor, not proof.
Content SDK personalization (head app)
Page-level personalization works out of the box: PersonalizeProxy asks for a decision on every request and rewrites to the variant, and getPage applies it. This skill covers that path, what breaks it silently, and what the SDK gives you when you trigger a decision yourself. The short answer to the second part: you can call personalize() from any runtime, but it only reaches flows that Pages or the Agent API created, and on the server a plain fetch is safer than the SDK.
Backend setup (analytics identifier, PAGES_PERSONALIZE_SCOPE, creating variants and A/B tests, the flow-level checks) belongs to sitecoreai-personalization. Consent wiring (Bootstrap, CdpPageView, Forms, withdrawal) belongs to content-sdk-tracking-consent. This skill links to both and does not repeat them.
When to use
- A personalized variant does not show on the live site, or shows for everyone.
- Wiring or reviewing
PersonalizeProxyandsitecore.config.ts → personalize. - Calling
personalize()from a client component, Route Handler, Server Component or a proxy subclass. - Reusing the proxy's decision in your own code, or applying a decision you made yourself.
- Deciding whether a site needs the proxy at all.
When NOT to use
- Creating page variants, audiences or A/B tests:
sitecoreai-personalization. - Sending page views, custom events or identity, or gating tracking on consent:
content-sdk-tracking-consent. - Tag-based cache invalidation in general:
content-sdk-app-router-cache-components-and-osr.
1. The OOTB path
Proxy chain (the scaffold's src/proxy.ts, instantiated per request with the NextFetchEvent):
preview → botTracking → locale → multisite → redirects → personalize
BotTrackingProxy must run before PersonalizeProxy, because personalize skips requests carrying the sc_bot cookie (skipForBot, default true). Sitecore's lightweight-tracking doc says bot tracking "must be the first proxy", but the scaffold puts preview first. Follow the scaffold. Some starter repos still ship a 4- or 5-proxy chain without bot tracking: that is drift, not a different design. src/proxy.ts alone is enough on Next 16; there is no middleware.ts (measured on Next 16.3.5).
What PersonalizeProxy does (nextjs/types/proxy/personalize-proxy.d.ts; full skip order in references/proxy-and-config.md):
- Returns early when disabled (
enabled:false, no Edge config, a path containing., orskip()returns true), on a redirect, on preview, or onsc_bot. - Reads the route's
personalization { variantIds }from Edge (edgeTimeout, 10 s in-process cache). - Returns on no personalization or on a prefetch (
Cache-Control: no-store,x-proxy-cache: no-cache). - Calls
initContentSdkwith the server context id. This setssc_cidandsc_cid_personalizewith both cookie flags hard-coded on. On a personalized route with marketing consent this is the guest mint:Set-Cookieon the document, and the browser'screate.jsondisappears (measured 2026-10-07; tests:references/verification.md§ Testing notes). - Sends one
personalize()per friendlyId in parallel (cdpTimeout), with UTM, referrer, User-Agent and the optional geo. - Drops any returned id that is not in the Edge list, then rewrites to
/<path>/_variantId_<page>[/_variantId_<comp>_<var>]. - Fails open: any error or timeout serves the default variant and only logs.
Applying the variant. page.tsx needs nothing special. client.getPage(path) parses the _variantId_ segments and runs personalizeLayout(layout, variantId, componentVariantIds) (content/types/personalize/layout-personalizer.d.ts:14). That swaps each rendering for experiences[id], removes variants whose componentName is null, and writes layout.sitecore.context.variantId. All variants travel in the Edge layout JSON; selection is server-side. A variant can swap a component's datasource, so a personalizable component must render any datasource of its template.
Config. Set the personalize block explicitly (keys, env names and the template trap in references/proxy-and-config.md):
// sitecore.config.ts
personalize: {
enabled: false, // site has no personalization: say so
// enabled: process.env.NODE_ENV !== 'development', // when it does
scope: process.env.SITECORE_PERSONALIZE_SCOPE, // must equal the CM's PAGES_PERSONALIZE_SCOPE
},
enableddefaults toNODE_ENV !== 'development', so every production request the proxy does not skip pays one Edge lookup, even on a site with no personalization. Measured from a client, that lookup costs about 36 ms p50 / 44 ms p95; the figure from a Vercel Node proxy is open[probe-gated: P13]. Setenabled:falseon sites without personalization: it removes the lookup and the noise.- Timeouts read
PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUTandPERSONALIZE_MIDDLEWARE_CDP_TIMEOUT(400 ms each). The template'ssitecore.config.ts.examplereadsPERSONALIZE_PROXY_EDGE_TIMEOUTfor both; a wrong or non-numeric value falls back to 400 silently. - Scope reads
SITECORE_PERSONALIZE_SCOPE→CSDK_PUBLIC_PERSONALIZE_SCOPE→NEXT_PUBLIC_PERSONALIZE_SCOPE. It is normalized to alphanumerics and embedded in every friendlyId. A head-app scope that differs from the CM'sPAGES_PERSONALIZE_SCOPEgives a friendlyId that no flow has. The exact failure response is open[probe-gated: P5].
Geo on Vercel. The proxy forwards only the User-Agent. Geo reaches the decision only through extractGeoDataCb (commented out in the scaffold with a hard-coded example). Without it, the OOTB country / country_region condition code falls back to the cf-ipCountry / cf-region-code request headers. Because the proxy makes the call server-side, those headers describe the hosting region, not the visitor, and geo audiences match by data centre, silently.
// in new PersonalizeProxy({...}). Header names are Vercel's documented geo headers (not in the
// evidence set); the value form the country condition expects (code vs name) is [probe-gated: P12]
extractGeoDataCb: (req) => ({
country: req?.headers.get('x-vercel-ip-country') ?? undefined,
region: req?.headers.get('x-vercel-ip-country-region') ?? undefined,
}),
Consent. The proxy's only consent levers are enabled and skip, both all-or-nothing. skip runs before the Edge lookup and before the cookie writes, so skip must read the visitor's consent state (a first-party cookie, because the proxy cannot see client state): skip: (req) => !hasConsent(req). A visitor without consent always gets the default variant. A grant does not reload, so the server decision sees it only on the next request: call router.refresh() on a denied → granted marketing transition (no reload; URL and utm_* kept; measured 2026-10-07). The consent cookie, Bootstrap gating and withdrawal live in content-sdk-tracking-consent.
2. Variant ids in one table
| Thing | Form | Example shape |
|---|---|---|
| Edge page variant id | no _ | <v> |
| Edge component variant id | <componentId>_<variantId>; <componentId>_default is the control | <c>_<v> |
| Page friendlyId | embedded_[scope_]<pageIdNoDashes>_<lang> | CdpHelper.getPageFriendlyId(pageId, lang, scope) |
| Component friendlyId | component_[scope_]<pageId>_<componentId>_<lang>* (* = fuzzy match) | CdpHelper.getComponentFriendlyId(...) |
| Rewrite path | /<path>/_variantId_<v>[/_variantId_<c>_<v>] | getPersonalizedRewrite(path, ids) |
VIEW pageVariantId | [scope_]<pageId>_<lang>_<variantId|default> | CdpHelper.getPageVariantId(...) |
All lowercased; the language replaces only its first hyphen with _. Worked examples and edge cases: references/variant-grammar.md.
3. Editing and preview
- Pages sends
sc_variant; since nextjs/content 2.2.0 Preview GraphQL resolves the variant server-side. No decision call is made in editing. - In editing,
personalizeLayoutrenders a hidden variant as the hidden-rendering placeholder instead of removing it, so the author can still select it. PersonalizeProxyandBotTrackingProxyskip preview; Bootstrap does not init indraftMode. A self-invoked browserpersonalize()therefore throws IE-002 in editing: branch onpage.mode.isNormal.next devdisables the proxy (enableddefault) and Bootstrap. Verify only on a production build against LIVE Edge (preview is the permissive surface).
4. Triggering a decision yourself
The primitive is personalize(data, { timeout }) from @sitecore-content-sdk/personalize (personalize/types/src/personalization/personalize.d.ts:10). It needs initContentSdk with analyticsPlugin and a personalize plugin, POSTs {edgeUrl}/v1/personalize?siteId=<siteName> with only x-sitecore-contextid, and returns the body typed unknown. The behaviour that matters:
- No
timeout→ no timeout at all. A timeout throws IE-003 but does not abort the fetch. - Non-2xx, network and JSON errors return
null. Init missing throws IE-002 / IE-004; blank friendlyId throws MV-004. browserId(fromsc_cid) is sent only when you pass noemailand noidentifier. Passing one switches to the identified guest and a separate session.- No bot check. Only the proxy honours
sc_bot; gate your own calls. - Check the returned
variantIdagainst the candidates you sent, as the proxy does.
Full wire body, error table and longer code: references/self-invocation.md.
| Runtime | How | Verdict |
|---|---|---|
| Client component | Add personalizeBrowserPlugin to Bootstrap's plugin array; call after init | OK. Never call initContentSdk a second time: it replaces Bootstrap's plugins |
| Route Handler | initContentSdk + analyticsProxyAdapter / personalizeProxyAdapter with a carrier response | Works, but not concurrency-safe |
| Server Component | Hand-written adapters over cookies() / headers(); both cookie flags false | Possible; same singleton risk; feed UTM from searchParams |
| Proxy | Subclass PersonalizeProxy; override the protected getExperienceParams / getPersonalizeExecutions | Best for extra params or extra friendlyIds: reuses init, rewrite and fail-open |
| Any server code | Plain fetch of the wire contract | Recommended for server use |
Why fetch on the server. initContentSdk overwrites one process-global context, and SDK calls read it back after an await. Measured with server-side event() in a Route Handler under 50 concurrent requests: 24/50 outbound calls carried another visitor's browser id, and 49/50 with 0-200 ms jitter, all accepted with 201, while Set-Cookie stayed correct. personalize() resolves its adapters the same way; the proxy and Route-Handler legs for personalize() specifically are [probe-gated: P22].
// server-side decision without the SDK singleton
const r = await fetch(`${edgeUrl}/v1/personalize?siteId=${encodeURIComponent(siteName)}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'x-sitecore-contextid': contextId, ...(ua && { 'User-Agent': ua }) },
body: JSON.stringify({
friendlyId, channel: 'WEB', currencyCode: 'USD', language, clientKey: '', pointOfSale: '',
browserId: sc_cid ?? '', guestRef: sc_cid_personalize ?? '',
params: { utm, referrer, geo }, variants,
}),
signal: AbortSignal.timeout(400), // a real abort, unlike the SDK's race
cache: 'no-store', // a decision is per visitor: never cache it
});
const variantId = r.ok ? ((await r.json()) as { variantId?: string }).variantId : undefined;
const chosen = variantId && variants.includes(variantId) ? variantId : undefined;
Reusing the proxy's decision.
- In
page.tsx, the rewrite lands in the[[...path]]param:getPersonalizedRewriteData(path.join('/'))returns{ variantId, componentVariantIds }(default'_default');normalizePersonalizedRewritegives the clean path (content/types/personalize/utils.d.ts). - Apply your own decision without the proxy:
client.getPage(path, { site, locale, personalize: { variantId, componentVariantIds } }). An explicitpersonalizewins over the path (PageOptions,content/types/client/sitecore-client.d.ts:86). - In client components only the page variant survives:
useSitecore().page.layout.sitecore.context.variantId. Component variant ids are not kept in the layout; pass them as a prop frompage.tsx. - Other proxies can read
SuccessfulPersonalizeProxyExecutionfromproxiesContext, but only if you pass aMapintoexec(req, res, ctx). The scaffold calls.exec(req).
What a self-invoked call can target. Only friendlyIds that exist in the Personalize tenant behind the context id. On a SitecoreAI embedded-only tenant those are the embedded_… and component_…* flows that Pages, the Agent API or the Marketer MCP created, and the response is fixed to { "variantId": "…" }. No Agent API, Pages API or MCP operation accepts a friendlyId, a flow type or a response template.
- Decision-as-data is a named gap. An arbitrary friendlyId that returns an arbitrary JSON payload is a standalone Sitecore Personalize interactive experience. The SDK would return such a body verbatim, but whether edge-platform
/v1/personalizeforwards a non-embedded flow is[probe-gated: unscheduled, needs a Personalize-licensed tenant]. - Embedded workaround, the "decision page": a hidden page whose variants carry the payload. Call its page friendlyId, then read
experiences[variantId]from its Edge layout (or runpersonalizeLayout). Measured (P7): Edge carries the copied datasource's fullfieldsunderexperiences[<v>]for a datasource-only COPY, and the decision ignores URL,siteIdand bodylanguage(friendlyId + params decide). So the decision side works from any route. Whether Pages accepts a hidden decision page is not run. webPersonalizationis not an option on embedded tenants. On both tenants probed,/v1/personalize/cdn-urlpointed at acloud-version.min.jsthat returns 403, so the plugin injects a script that does nothing. Itsdeferandlanguageoptions are ignored, and browser init exposeswindow.scContentSDK.personalizeto every script on the page.
Client-side decisions on a cached or static page keep one HTML cache entry, but only client components can swap to experiences[variantId]; Server Components cannot re-render. Expect flicker: default first, then init, create.json on a first visit, and the decision round trip.
5. Caching
| Behaviour | Status |
|---|---|
Personalized responses get x-proxy-cache: no-cache; prefetch skips the decision with Cache-Control: no-store | code-verified |
generateStaticParams emits base paths only, so variant paths render on demand | code-verified |
'use cache' keyed on {site, locale, path} gives one entry per variant path; cache tags strip variant segments, so one revalidate covers all variants | inference from code |
| Vercel CDN / ISR cache key for a rewritten request; audience leakage | [probe-gated: P17] |
A third-party CDN in front sees no Vary: Cookie or Cache-Control: private; bypass personalized routes there | from code reading, not measured |
Never cache a self-invoked decision (fetch cache, 'use cache', CDN) | rule |
6. Verify: the head-app layers
The rendered page proves nothing, because the decision fails open. Check each layer separately, each with a control. Layers 1-2 (flow, variant setup) and 7 (analytics) are in sitecoreai-personalization. Commands and pass criteria: references/verification.md.
| Layer | Pass | Control |
|---|---|---|
| 3 Edge | personalization.variantIds non-empty; the rendering has experiences[<v>] | A plain page returns [] (never null) and has no experiences key |
| 4 Decision | Direct POST /v1/personalize with a real browser id returns { variantId: <v> } | Same call without the matching condition: 200 {"message":"No matching variant"}. Unknown or wrongly scoped friendlyId: 404 No experiences found for friendlyId … and clientKey … (measured P7) |
| 5 Render | Production build, LIVE Edge, non-headless UA, consent set, DEBUG=content-sdk:personalize shows the _variantId_ rewrite | Without the condition: the default |
| 6 Beacon | VIEW ext.pageVariantId ends _<v> | A default visit ends _default |
Never judge from one request. The proxy's Edge lookup has a 400 ms budget (PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT). The first request after next start, and the first after a publish (Edge cache cold), hit IE-003 (measured: 411 ms, 406 ms) and serve the default as skipped (personalize info not found). Warm the route, or raise the timeout, and repeat. On the deployed CDN (2026-10-07) the first request after publish + redeploy served the default with a live variant, and identical repeats then alternated default / variant for a while: warm, re-read several times. The content-sdk:personalize DEBUG log prints the full context id in every lookup: do not ship it to a log vendor.
A headless browser is a bot. isbot classifies HeadlessChrome and curl, so sc_bot is set and the proxy skips. Pin a real Chrome UA and assert a positive control before trusting a zero.
Hard rules
- Set
personalize.enabledexplicitly;falseon a site without personalization. skipreads consent. Never let the proxy run, and set cookies, for a visitor without consent.- Keep
BotTrackingProxybeforePersonalizeProxy. - Pass a
timeoutto every SDKpersonalize()call, and catch IE-002 / IE-003. - Server-side self-invocation uses
fetch, not the SDK, unless the calls are serialized. - Never treat a rendered page, a quiet console or a zero under a headless UA as proof.
Stop conditions
- Stop if asked to make decision tables work from the head app: there is no API, and the head-app contract is undocumented
[probe-gated: P9]. Route to the Pages UI. - Stop if a fix needs a custom flow type or response template on an embedded-only tenant: that is the decision-as-data gap.
- Stop and probe before relying on locale-prefixed URLs: the proxy looks up the raw pathname, so
/de/aboutprobably never personalizes[probe-gated: P11].
References
references/proxy-and-config.md: skip order, config keys, env vars, proxy hooks.references/variant-grammar.md: id and friendlyId formulas with worked examples.references/self-invocation.md: wire body, errors, code per runtime.references/verification.md: the ladder with commands, plus testing notes.references/traps.md: every known trap with its status.- Sibling skills:
sitecoreai-personalization,content-sdk-tracking-consent,content-sdk-app-router-multisite-management,content-sdk-app-router-cache-components-and-osr,content-sdk-app-router-route-handler-vs-server-action.
Content SDK — Playground Pattern
A throwaway learning workspace, kept apart from production code. It lets you and an agent explore patterns (resolvers, integrated GraphQL, SCS shapes, multisite, editing) against a real SitecoreAI tenant without touching a real project.
When to use
- The user asks to "learn X," "play with Y," "try Z," or to investigate a Sitecore feature against a real tenant without committing to a project.
- Validating an assumption about layout response shapes, resolver behavior, or SDK contracts before scaffolding a real Marketplace app or head app.
- Capturing real-tenant fixtures (introspection JSON, layout captures) that real projects can reuse.
- Onboarding the agent on a new Sitecore subsystem (for example, the first time you use a feature you've never built against).
How to perform
- Choose a topic-scoped folder, outside any real project, for example
playground-navigation/orplayground-redirects/. Keep it out of real project folders so their tooling and CI never pick it up. - Scaffold the SCS solution side with
dotnet sitecore plugin add Sitecore.DevEx.Extensibility.XMCloud@<v>, thendotnet sitecore init, then declare modules inauthoring/items/<module>.module.json. Connect to a Cloud environment per thesitecoreai-cli-cloud-workflowskill. - Scaffold the head app side inside
sites/<topic>/withnpx --yes create-content-sdk-app@latest --yes --template nextjs-app-router --destination sites/<topic>(per thesetup-content-sdkskill, which also covers the Pages Router template). Treat this as a regular Content SDK head app —src/,.sitecore/, etc. - Wire
xmcloud.build.jsonat the playground root to pointrenderingHosts.<host>.pathat./sites/<topic>. - Capture an Edge snapshot at the start. Create
edge-snapshot/and save (capture-edge.mjsin thesitecoreai-edge-graphql-captureskill does this; Edge rejects a full introspection query, so it introspects per type):sites.json,routes.json— sites and routes query responsestype-<T>.json— one per relevant root type (Item, ItemField, LayoutData, RoutesResult, SiteData, SiteInfo)layouts/<page-or-pattern>.json— layout response per page that demonstrates a pattern
- Write findings down in a notes file in the playground, or wherever your agent keeps long-lived notes, with the playground path. Future sessions then know where to look.
- Install the
content-sdk-debug-layout-probetoolkit in the head app on day one — it pays for itself within an hour.
Hard Rules
- The playground lives outside real projects. Putting it inside one makes that project's tooling treat throwaway code as real.
- Each playground owns exactly one tenant + one rendering host config. Switching tenants mid-playground invalidates the captured Edge snapshot.
- Keep
authoring/in source control with serialized items committed. That's how the agent can reason about templates, renderings and parameters without a live tenant. edge-snapshot/is captured, not regenerated on every change. Re-pull intentionally when the schema changes (new templates, breaking renderings).- The head app under
sites/<topic>/follows all the rules of a real head app — sameAGENTS.md, same Tailwind/Next config, same component map. Treat it as production-quality even if it's "just a playground." - Don't ship playground code to production. It's a learning artifact; reference patterns, copy with attribution, don't deploy.
Stop Conditions
- Stop and ask if the user is unsure whether the new work is a real project or a playground. A real project has a roadmap and owners; a playground is exploratory and disposable.
- Don't merge multiple Sitecore features into one playground — keep one topic per playground so the captured artifacts stay legible.
- Don't reuse a real project's Cloud environment for a playground. Authoring changes in the playground will pollute the project.
What lives where
playground-<topic>/
sitecore.json # SCS root config (modules glob)
xmcloud.build.json # rendering host config (points at ./sites/<topic>)
.sitecore/ # CLI-provisioned schemas + user.json (gitignored)
authoring/
<topic>.sln # full .NET SCS solution
items/<topic>.module.json
items/items/ # serialized YAML
sites/<topic>/ # scaffolded Content SDK head app (Next.js App Router)
src/, .sitecore/, etc.
edge-snapshot/ # per-type introspection + per-pattern layout captures
sites.json, routes.json
layouts/<pattern>.json
type-<T>.json
Verification
dotnet sitecore ser pull -n <env>from the playground root succeeds and updatesauthoring/items/items/...deterministically.npm run devinsites/<topic>/boots and renders pages from the tenant.- The Edge snapshot can be diffed across pulls to detect tenant-side drift.
Related
setup-content-sdk— the scaffold forsites/<topic>/.sitecoreai-cli-cloud-workflow— for theauthoring/side.sitecoreai-edge-graphql-capture— foredge-snapshot/.content-sdk-debug-layout-probe— install this insites/<topic>/on day one.content-sdk-resolver-patterns— the catalog of patterns a playground exists to learn.
References
- SCS structural overview
- xmcloud-starter-js repo — reference SCS layouts
Content SDK — Resolver Patterns
Sitecore can hand the same React component its data in several fundamentally different shapes. The SDL says nothing about which — it just types LayoutData { item: Item }. This skill catalogs the patterns, points at the 4 confirmed SXA-foundation resolver GUIDs, and — most importantly — shows that the 4 content-resolver variants only produce 2 distinct React-side shapes.
Content resolvers are not supported with Edge runtime publishing (Sitecore docs), and nothing documents their output as editable in Pages. This catalog tells you what a payload is; to choose a delivery for a list, use
content-sdk-collection-data-model.
When to use
- Planning a new Sitecore component and asking "what does my React component receive?"
- Reading an unknown rendering item's YAML and trying to figure out which delivery model it uses.
- Reviewing a layout response and trying to classify each rendering's pattern.
- Deciding between writing a Content Resolver in C# vs an Integrated GraphQL query vs auto-serialized fields.
- Onboarding the agent on Sitecore data delivery for the first time.
The five patterns
1. Standard Datasource
Rendering YAML signals: Datasource Template field set; no ComponentQuery; no Rendering Contents Resolver field set; dataSource populated on placeholder entry.
Payload shape:
{
"componentName": "Promo_Training",
"dataSource": "/sitecore/content/.../Data/Promo",
"params": { "GridParameters": "col-12", "FieldNames": "Default" },
"fields": {
"Title": { "value": "..." },
"Image": { "value": { "src": "...", "alt": "...", "width": "...", "height": "..." } },
"Link": { "value": { "href": "..." } }
}
}
React shape: <Text field={fields.Title}/>, <Image field={fields.Image}/>, <Link field={fields.Link}/>. Zero GraphQL, zero C# — the layout service auto-serializes every field on the datasource template.
2. All-Fields Datasource (same as Standard, plus field-type catalog)
Same payload as Standard, but exercises every Sitecore field type. The non-obvious shapes:
| Field type | Shape | Trap |
|---|---|---|
| Single/Multi Line, Rich Text | { value: "string" } | — |
| Image, File | { value: { src, alt, width, height, mimeType?, size? } } | File has richer fields than Image |
| General Link | { value: { href, text?, target?, linktype?, ... } } | — |
| Checkbox | { value: boolean } | — |
| Integer, Number | { value: number } | — |
| Date, Datetime | { value: "ISO" } | — |
| Droplink, Droptree | { id, url, name, displayName, fields: {...} } | No value wrapper — full item inline |
| Treelist, Multilist, Checklist | [ { id, url, name, displayName, fields: {...} }, ... ] | Array of full items, no value wrapper |
| Droplist | { value: "string" } | Looks like Droplink, isn't. Just a string of the picked option name. |
SDK field components (<Text>, <RichText>, <Image>, <Link>, <DateField>, <File>) consume the {value:...} shapes. Lists/refs you render yourself.
3. Integrated GraphQL
Rendering YAML signals: ComponentQuery field populated with a GraphQL query string (using $datasource: String! and $language: String! variables); Datasource Template typically still set; Rendering Contents Resolver may be empty.
Payload shape:
{
"componentName": "LinkList_Training",
"dataSource": "/sitecore/.../Data/LinkList",
"params": { ... },
"fields": {
"data": {
"datasource": {
"field": { "title": { "value": "..." } },
"children": {
"results": [ { "field": { "link": { "value": { "href": "..." } } } } ]
}
}
}
}
}
The shape of fields.data mirrors the GraphQL query's aliased structure. Use when the flat field hash can't express the need (children traversal, filtering, aggregation, cross-item joins). Cost: query lives on the rendering item itself.
A rejected query does not error; it empties the component. When Edge refuses a ComponentQuery (complexity, depth, or children nested two levels deep), the rendering arrives with isContentResolved: false and no fields, and nothing is logged. Treat isContentResolved: false on a pattern-3 rendering as a query-budget failure first. Re-run the query directly against Edge to see the error text, and size it with sitecoreai-edge-graphql-capture § 2b (measured 2026-09-26 → 28).
4. Content Resolvers (.NET) — the 2×2 family
Rendering YAML signals: Rendering Contents Resolver field set to a resolver GUID; dataSource typically populated (even when the resolver ignores it — SXA requires it for Pages chrome).
The SXA Headless foundation ships four resolver classes that form a 2×2 matrix on two axes — source (where the data comes from) and cardinality (item or its children):
Datasource (read from dataSource field) | Context (read from current page item) | |
|---|---|---|
| Single item | {3DF775BF-3F56-446F-9D81-43DE64DA4DDA} Datasource Content Resolver | {6CCCBCDE-5E95-44E4-AE66-CFE7D3A0589E} Context Item Resolver |
| Children list | {2F5C334E-5615-423C-8281-9FC180191302} Datasource Children (the standard SXA "Datasource Resolver") | {207769CC-38C0-4DE1-B893-A6B037B3AEC4} Context Children Resolver |
(GUIDs verified against a real SitecoreAI tenant on 2026-05-27. They are SXA foundation items, not project-specific.)
The Navigation Content Resolver is a separate, non-2×2 resolver — see the ## Navigation section below (open question; not yet fully verified).
5. Custom .NET resolvers (anything outside the 2×2 family)
Rendering Contents Resolver set to a GUID NOT in the table above → custom resolver class. Shape is opaque from outside — probe with the content-sdk-debug-layout-probe toolkit before writing the component.
React-side reality: only 2 shapes to code against
Despite the 2×2 of resolvers, the React side only sees two distinct payload shapes:
Shape A — Single-item
type SingleItemPayload = {
[FieldName: string]: SitecoreField; // { value: ... } or full item ref shape
};
Produced by: Datasource Content Resolver, Context Item Resolver, Standard Datasource pattern (1), All-Fields Datasource pattern (2).
Read with: SDK field components (<Text>, <RichText>, <Image>, <Link>, <DateField>, <File>).
Shape B — Children list
type ChildrenPayload = {
items: Array<{
id: string;
url: string;
name: string;
displayName: string;
fields: Record<string, SitecoreField>;
}>;
};
Produced by: ChildrenContentResolver, Context Children Resolver.
Read with: custom rendering (no SDK component is "list-shaped"). Each items[i].fields is itself shape A — recurse with the SDK field components per item.
Consequence: one React component can serve both members of each pair (Datasource ↔ Context). The only difference is the source, which doesn't affect how you render — the shape is identical. So ContentResolverProbe and ChildrenResolverProbe are the only two probes you actually need; the 4-file split is over-specified.
The universal item-reference shape
{ "id": "...", "url": "...", "name": "...", "displayName": "...", "fields": { ... } }
This shape appears in three places:
- Droplink / Droptree fields (All-Fields pattern, single)
- Treelist / Multilist / Checklist field values (All-Fields pattern, array)
items[i]in any Children-resolver payload (Shape B above)
Practical implication: the rendering code for "an item reference" is reusable across all three. Write one <ItemCard> and reuse.
Empty-state field shapes (defensive reads required)
A new content item with no values populated produces these — they are NOT the typed defaults you might expect:
| Field type | Empty-state shape | Defensive read |
|---|---|---|
| Single Line / Multi Line / Rich Text | { value: "" } | fields.Title?.value (will be empty string, not null) |
| Image | { value: {} } (empty object, NOT {src:"", alt:"", width:"", height:""}) | fields.PromoIcon?.value?.src |
| General Link | { value: { href: "" } } (only href, missing other props) | fields.PromoLink?.value?.href |
| Checkbox | { value: false } | fields.Active?.value |
| Date / Datetime | { value: "" } or { value: "0001-01-01T00:00:00Z" } | fields.PublishDate?.value |
| Item references (Droplink, Treelist, etc.) | null or [] | fields.Related?.id ?? '' / (fields.Items ?? []).map(...) |
Always optional-chain to the deepest leaf. Don't assume value is always defined on the inner object.
How to identify the pattern (from rendering YAML)
inspect rendering item under /sitecore/layout/Renderings/.../<Name>.yml
Has ComponentQuery field populated AND no Rendering Contents Resolver?
→ Pattern 3 (Integrated GraphQL)
Has Rendering Contents Resolver GUID populated?
Match against the 2×2 table?
→ Pattern 4 (Content Resolver, one of the 4 known) — use Shape A or B
Else
→ Pattern 5 (Custom resolver) — probe to learn shape
Else dataSource on placeholder is non-empty + no resolver?
→ Pattern 1 or 2 (Standard / All-Fields Datasource) — Shape A
Else
→ Likely buggy / unfinished — probe to confirm
Note: When BOTH ComponentQuery AND Rendering Contents Resolver are set on a rendering, the resolver wins — fields carries the resolver's shape, not the GraphQL shape. The query is dormant. Verified on Context Children Resolver during the 2026-05-27 capture.
Navigation (open question — parked)
Navigation_Training uses a navigation-specific resolver (NOT one of the 4 in the 2×2). Behavior depends on LevelFrom / LevelTo / Filter / AddRoot params. As of 2026-05-27 the current state returns fields: [<single root item>] (with AddRoot=1), but the full multi-level tree behavior isn't fully verified. Approach for now: build navigation with component-level data fetching using a custom GraphQL query rather than fighting the resolver, and treat the resolver as "use it when behavior matches; otherwise replace with a query."
Hard Rules
- The SDL only types
LayoutData { item: Item }. Everything insiderendered.sitecore.{context,route}is untyped JSON. There is no schema-level type safety forfields. Patterns are runtime contracts, not type contracts. - Identify the pattern BEFORE writing the React component. Wrong assumption = empty render at best, runtime crash at worst.
- For unknown resolvers, ALWAYS scaffold a
ResolverProbedummy first (seecontent-sdk-debug-layout-probe). Capture the shape, then write the real component. - Two probes are enough, not four — one for Shape A (single-item) and one for Shape B (children-list) cover the entire 2×2 of content resolvers.
- SDK field components (
<Text>,<RichText>,<Image>,<Link>) only consume{value:...}shapes. For Droplink/Droptree/Treelist/Multilist/Checklist and Children-resolveritems[i].fields, render manually usingitem.fields.<FieldName>.value. - Droplist is a string, not an item reference, despite its name suggesting Droplink kinship. Don't try to render
Droplist.id— it doesn't exist. - Always optional-chain to the deepest leaf. Empty-state shapes are NOT the populated shape with empty strings — they're often missing inner keys entirely (
{value: {}}for an empty Image). dataSourceis always populated on Context-resolver renderings even though the resolver ignores it — SXA requires it for Pages chrome. Don't try to "fix" the apparent disconnect.- Resolver GUID wins over ComponentQuery when both are set. The query is dormant; the resolver's shape comes through. To switch to GraphQL, clear the resolver field.
- Integrated GraphQL queries run on every layout fetch — keep them lean. They cost more than auto-serialized fields.
- Content Resolvers can fall back to defaults silently — if
dataSourceis empty AND the resolver auto-resolves to the site root, you might see results from a different item than you expect. Verify with the layout probe. - Empty
fields: []from a Content Resolver is NOT a bug — it means the resolver ran successfully and found nothing. Check the resolver's required params and the source items.
Stop Conditions
- Don't infer the pattern from the rendering's NAME alone. Read the YAML — the name can lie (e.g., "Context Children Resolver" could in principle use Integrated GraphQL; only the rendering item tells you which it actually is).
- Don't assume a shape from one capture. Resolvers may behave differently based on params, page context, or content tree state. Capture multiple states (different pages, different params) before locking in a TypeScript type.
- Don't write a TypeScript type from prose docs. Capture from a real Edge response. The doc shape and the runtime shape drift.
Verification
- For any new rendering, the React component should render correctly against the live layout response (use
content-sdk-debug-layout-probeto capture). - For Children-resolver renderings, verify the
items[i].fieldsshape against your expected per-item field set. The wrapper is always{items:[...]}; only the innerfieldsvaries. - The InstrumentedFrame
toneshould match the identified pattern (accent / ok / warn / ink) — that's a visual sanity check. - If
fieldsis undefined/null/empty when it shouldn't be, return to the rendering YAML and re-verify the pattern (especially the resolver-GUID-vs-ComponentQuery precedence).
Related
content-sdk-debug-layout-probe— the probe toolkit for discovering payload shapes.content-sdk-component-naming-traps— for getting the file structure right once the shape is known.content-sdk-field-usage-image-link-text— SDK field components for Shape A.content-sdk-app-router-graphql-data-fetching— for Integrated GraphQL (pattern 3) and the recommended approach for Navigation (component-level queries).
References
- SXA Headless Content Resolvers overview
- Integrated GraphQL on rendering items
- Evidence: four base-pattern layout captures plus the four content-resolver variants captured live through
/api/layout-debug?path=/Components/Content-Resolvers(content-sdk-debug-layout-probe) on 2026-05-27; the payload shapes in this skill are transcribed from those captures.
Content SDK: integrated search (head-app side)
SitecoreAI Search experiences ("integrated search") is queried from the head app with ONE public credential, the Edge context id, sent as x-sitecore-contextid to POST https://edge-platform.sitecorecloud.io/v1/search and /v1/search/suggest. No API key, no OAuth, no customer key. The index itself (a search source) is configured in the SitecoreAI UI: that half lives in the sitecoreai-search-sources skill.
Status markers: [confirmed] = measured on 2026-10-02 (live read-only probe or a local Next 16 build); [source] = read from the installed SDK; [probe-gated: Pn] = not proven yet, named probe closes it.
Not this
| You want | Use | Not |
|---|---|---|
| Site/product search with marketer-tuned boost, pin, facets | this skill + sitecoreai-search-sources | Edge GraphQL search(where:) (filters an item's own fields only) |
| Exact structural queries (children of X, by template) inside a data fetch | Edge GraphQL / ComponentQuery (sitecoreai-graphql-schemas) | integrated search (index lags until a manual reindex) |
Recommendations, widgets, rfk_id, customer key, discover.sitecorecloud.io | standalone Sitecore Search (CEC) | this skill |
| CM item lookup during authoring automation | Authoring GraphQL search(query:) | either search product |
Preflight (all must pass before UI code)
- A source id exists. Read it from the source's Settings tab (the "ID" is the
searchIndexId), or list sources with the search-config script ofsitecoreai-search-sources(needs a credential with the search-config scope). No source, no search: an unknown id answers 404no search index found for config <id>[confirmed]. - SDK floor:
npm ls @sitecore-content-sdk/search. Search rides on nextjs (nextjs → react → search). 0.4 (nextjs 2.3) addslocale+facet; 0.5 (nextjs 2.4) addssuggest()+ MLT. Table:references/version-matrix.md. NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_IDis set (api.edge.clientContextId). Without ituseSearchService()returnsnulland every hook staysstatus: 'idle'forever with zero requests and no error [confirmed: P8, 0 requests in 5 s]. A missingsearchIndexIdinstead givesstatus: 'error'.- Live probe passes:
node scripts/probe-search.mjs --context-env NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID --env-file .env.local --index <id>. It runs a fake-context control first (must be 404No sitecore context), then a fake-index control (must be 404no search index found), then your query.
Choose the surface
| Situation | Use |
|---|---|
| Interactive search box, pagination | useSearch / useInfiniteSearch from @sitecore-content-sdk/nextjs/search, in a 'use client' component, inside a component-local <Suspense> |
| Typeahead | useSuggest (no built-in debounce: debounce the input yourself) |
| SEO-visible results, a "related content" block, a route handler | new SearchService({ contextId }) on the server |
| Related items | MLT: seedItemId or seedItemUrl (site indexes only) instead of keyphrase; mutually exclusive [source]. GUID form [probe-gated: P4] |
Import paths [source]. Hooks come only from the /search subpath; the docs' root-path import does not exist. SearchService is not re-exported by nextjs or react: import it from @sitecore-content-sdk/search and add that package as a direct dependency pinned to the version npm ls shows (it is only transitive, so strict package managers will not resolve it).
Client-only rule [confirmed]. The hook dist files carry no 'use client'. A Server Component calling useSearch compiles fine and then fails at prerender with TypeError: (0 , c.useState) is not a function (a dynamic route would fail at request time instead). Put the directive on the file that calls the hook.
Server-side SearchService [confirmed: P8, Next 16.3.5]
- Works in a Server Component.
fetchOptionsis spread into the globalfetch, so Next caching applies: with{ next: { revalidate: 60 } }the page prerenders at build (one upstream POST) and repeat requests inside the TTL cause zero upstream calls; underdynamic = 'force-dynamic'the same option still dedupes through the data cache (1 upstream call for 3 requests);{ cache: 'no-store' }calls every time. - On the server
sessionIdis''(no analytics init): search works but is not tied to a CDP session. - Errors throw
Error('HTTP 404 Not Found')withe.response.statusande.response.data({ errors: [{ message, code }] }). Catch it and render an empty state; do not let a missing index 500 the page. - Type the call:
search<MyDoc>(…). The defaultSearchDocumentvalue type is not aReactNode, so{r.results[0].title}fails type-check. - Whether a preview context returns different (draft) content than live [probe-gated: P4]. Both ids are accepted by the search plane [confirmed].
Hooks: the rules that bite
- Memoize every
sortandfacetobject [confirmed: P8]. They areuseCallbackdependencies compared by reference. An inlinefacet={{ all: true }}produced 6,568 requests in 5 s, 6,600 renders, status stuck atloading(each render aborts the previous request). TheuseMemoversion sent exactly 1.check-search-wiring.mjsfails the inline form. limitmax 500 (RangeError);limit: 0passes validation [source]. An empty keyphrase returns the whole index.pageis 1-based;useInfiniteSearch.hasNextPage = results.length < total.- Each new request aborts the previous; aborted errors are suppressed.
- Hooks do not pass
localefor you. Pass the route locale explicitly on a multi-language site; the accepted format (envsen-US) [probe-gated: P4]. - Facet
nameis the facet's display name from the source config, not the raw field name (SDK JSDoc). Operatorseq|gt|lt|ge|le; string/boolean fieldseqonly; an array value means OR. Server behaviour [probe-gated: P4]. Discover names withsearch-config.mjs.
Recipe: port the starter SearchExperience
The only official consumer is the SYNC starter (xmcloud-starter-js/examples/kit-nextjs-product-listing/src/components/search-experience/). Copy it, then fix these on the way in (diffs in references/starter-port.md):
- Encode
?q=.useRouter.tsxbuilds`?q=${value}`;&,#,+corrupt the URL. UseencodeURIComponent(value). - Compute
nullResults.useEvent.tsxhard-codesnullResults: false, so the dashboard's Null searches KPI can never fire. Passtotal === 0. - Gate the event on consent. The starter calls
event()directly. Route it throughtrackEvent()fromcontent-sdk-tracking-consent(analytics category). Consent denied: no event, andsessionIdis'', but search itself keeps working. - Keep
<Suspense>local.useSearchParamsneeds a boundary fornext build; the starter wraps all ofProviders, which makes the whole tree client-rendered. Wrap only the search component. - Type
SearchDocumentfrom your source's real fields (the starter hard-codes SYNC product fields). Capture a response withprobe-search.mjs --outfirst. - Fail loudly on bad config.
useSearchFieldfalls back silently on an empty value,console.warns on invalid JSON, and casts valid JSON without validation (missingsearchIndex→undefined). In editing, render an author-visible notice instead. - Also: the starter omits
componentInstanceIdfrom the event (A/B/n attribution); itsmd:${baseClass}grid class is built at runtime and is invisible to Tailwind's scanner, so safelist the threemd:grid-cols-*classes.
CM side: the datasource template has ONE field search of type Plugin (Source = the Search Configuration Manager app) holding JSON { "searchIndex": "<source id>", "fieldsMapping": { title, description, type, link, images, tags } }. Rendering SearchExperience, variants Default (useSearch, pages) and LoadMore (useInfiniteSearch), rendering parameter columns 1-3, dictionary keys SearchExperience_*. Item inventory: references/starter-port.md. The exact JSON the app writes [probe-gated: P7].
Editing, preview and verification
- Search is disabled in Page Builder and Preview by design ("available only on published pages"). Run the hooks only when
!isEditing && !isPreview; render skeletons otherwise. - So a preview pass proves nothing: verify on a published page or with
probe-search.mjsagainst the live context. A test pass must list "search returns results" as unverifiable until the source is indexed and the page published. - Content sources do not refresh on publish: a new item appears only after a manual Reindex content (
sitecoreai-search-sources).
Authorability
Results are index documents wrapped into fake { value } fields; they are not Sitecore fields and not editable. Record a per-field waiver for the result fields in .authorability-ignore.json with that reason. The search config field is authorable (Plugin field, Search Configuration tab).
Analytics
The starter's event is event({ type: 'search', siteId, channel: 'web', name, language, core: { componentId, interactionType: 'viewed' | 'clicked', keyword, nullResults } }), needing analyticsPlugin + eventsPlugin (content-sdk-analytics-events). type: 'search' is a documented SitecoreAI event, distinct from standalone Search's SC_SEARCH_WIDGET_*. Whether these events reach Performance > Search, and whether a debounced viewed per keystroke inflates the counts [probe-gated: P7]. keyword is user input: treat it as potentially personal data.
Scripts
scripts/probe-search.mjs --context-env <VAR> [--env-file <f>] [--index <id>] [--keyphrase <q>] [--facet-all] [--suggest <q>] [--locale <l>] [--expect-results] [--out <file>]— read-only; controls first; never prints the context id. Exit 1 when a control or the query fails.scripts/check-search-wiring.mjs --app <dir> [--json]— static gate. FAIL: hook file without'use client', hooks imported from the package root, inlinesort/facetliteral or one built in the render body withoutuseMemo, unencoded?q=,nullResults: falseliteral,type: 'search'event with no consent guard. WARN:SearchServicewithout a direct@sitecore-content-sdk/searchdependency, no client context id in env files, hook call withoutlocale, search event withoutcomponentInstanceId,<Suspense>wrappingProviders, runtime-built Tailwind classes.- Both:
--self-testruns fixtures plus a mutation sweep that disables each guard in turn and fails if no case notices.
Traps index
- Bad context id → 404
No sitecore context(problem+json), not 401; the same for no header at all. Do not read it as "endpoint missing". - Unknown index with a good context → 404
{"errors":[{"message":"no search index found for config <id>","code":404}]}. - Missing client context id → hooks idle forever, silently.
- Inline
sort/facet→ request storm. - Hook in a Server Component → prerender
useState is not a function. SearchServiceneeds a direct@sitecore-content-sdk/searchdependency.- Empty keyphrase returns everything;
limit: 0is accepted. - Search does not run in Page Builder or Preview.
- Starter: unencoded
?q=,nullResults: false, ungatedevent(), Suspense around Providers, nocomponentInstanceId, runtime Tailwind class. - Do not confuse CM Solr
search(...), Edgesearch(where:), standalone Search and integrated search.
Related
sitecoreai-search-sources (sources, reindex, push, config read) · content-sdk-tracking-consent (trackEvent) · content-sdk-analytics-events · content-sdk-app-router-editing-safe-rendering · content-sdk-variants-vs-siblings (Default / LoadMore) · content-sdk-component-naming-traps (support files under src/components/ auto-register) · content-sdk-upgrade-assistant.
Content SDK Site Setup and Environment
Central config in sitecore.config.ts; all secrets and environment-specific values via env vars. The config file and the env-var conventions below are identical in App Router and Pages Router. Only locale/i18n wiring is router-specific, and that belongs to the dictionary-and-i18n skill (pointer in Hard Rules).
When to use
- User asks to configure site, default language, API host, or environment.
- Task involves sitecore.config.ts, .env, or defaultSite/defaultLanguage.
- User mentions "config," "environment variables," "API key," or "default site."
How to perform
- Edit
sitecore.config.tswithdefineConfig; read all secrets and env-specific values fromprocess.env.*. Add or change vars in.env.example(or.env.remote.example/.env.container.example) with placeholders; never commit.envor.env.local.
Hard Rules
- Use
sitecore.config.tswithdefineConfigfrom the SDK. Expose api (edge, local), defaultSite, defaultLanguage, editingSecret, multisite, redirects, personalize as needed. - All sensitive or environment-specific values must come from environment variables (e.g. process.env.SITECORE_API_KEY). Never hardcode API keys, secrets, or production URLs in source.
- Document every new or changed env var in
.env.example(or.env.remote.example/.env.container.example). Use placeholder or empty value and a short comment; never put real secrets in example files. - Never commit
.envor.env.local; they are gitignored. Example files are the source of truth for which vars exist. defaultLanguageresolves config →NEXT_PUBLIC_DEFAULT_LANGUAGE→en.- Locale/i18n wiring is router-specific and out of scope here: App Router uses next-intl (
src/i18n/routing.ts+request.ts) and[site]/[locale]route segments; Pages Router uses thei18nblock (locales,defaultLocale) innext.config.jswith per-requestcontext.locale. For that, usecontent-sdk-app-router-dictionary-and-i18norcontent-sdk-pages-router-dictionary-and-i18n(and the matching route-configuration skill).
Personalization and analytics settings
Verified against @sitecore-content-sdk/content 2.3.0 dist/cjs/config/define-config.js (defaults, lines 46-59; deepMerge skips undefined/'', lines 99-121; NaN fallback, lines 133-138), @sitecore-content-sdk/nextjs 2.4.0 dist/cjs/config/define-config.js:15 (the Next.js pre-fill), @sitecore-content-sdk/nextjs 2.4.0 dist/cjs/proxy/bot-tracking-proxy.js:128, and the create-content-sdk-app@2.4.0 App Router template.
| Var / key | Effect |
|---|---|
personalize.enabled (no env var) | Defaults to NODE_ENV !== 'development', so on in every production build. Each request the proxy does not skip pays one Edge lookup (up to edgeTimeout), even on a site with no personalization. Set enabled: false when the site does not personalize |
SITECORE_PERSONALIZE_SCOPE → CSDK_PUBLIC_PERSONALIZE_SCOPE → NEXT_PUBLIC_PERSONALIZE_SCOPE | personalize.scope. The base chain takes the first non-empty, but on Next.js the nextjs defineConfig pre-fills scope from NEXT_PUBLIC_PERSONALIZE_SCOPE, so a non-empty NEXT_PUBLIC_ value wins over SITECORE_. Set one name, not two that disagree. Must equal the CM environment's PAGES_PERSONALIZE_SCOPE. The template's .env.remote.example lists only NEXT_PUBLIC_, which CdpPageView also needs in the browser |
PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT / PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT | personalize.edgeTimeout / cdpTimeout in ms, default 400 each |
NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID | api.edge.clientContextId: the browser context id Bootstrap and <Form> use. Its presence enables browser tracking: the template's Bootstrap.tsx calls initContentSdk only when it is set (and never in development or preview) |
NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME | api.edge.edgeUrl; empty = https://edge-platform.sitecorecloud.io |
SITECORE_ENABLE_BOT_TRACKING=true | Turns BotTrackingProxy on in development / localhost, where it is off by default |
- Template trap: the scaffold's
sitecore.config.ts.examplesetsedgeTimeoutandcdpTimeoutfromPERSONALIZE_PROXY_EDGE_TIMEOUT, a namedefine-configdoes not read. If you copy it, one var drives both timeouts, and when it is unsetparseIntyieldsNaN, whichresolveConfigsilently replaces with thePERSONALIZE_MIDDLEWARE_*/ 400 default. No error either way. Use thePERSONALIZE_MIDDLEWARE_*names, or omit the keys. defineConfighas no analytics or events keys; those are plugin options (content-sdk-analytics-events).- Runtime tracking needs no OAuth credential, only the context ids above (
sitecoreai-auth§ 0b). - Wiring and behaviour:
content-sdk-personalization(proxy, scope, variants),content-sdk-analytics-events(Bootstrap, events),content-sdk-tracking-consent(gating all of it on consent).
Stop Conditions
- Stop if the user wants to commit real secrets or production values; insist on env vars and .env.example only.
- Stop if adding a new env var would require CI or deployment changes without explicit instruction; document the var and note that deployment must set it.
- Do not edit .next/, node_modules/, or lockfiles unless the task explicitly requires it.
References
Content SDK: Tracking Consent
A stock Content SDK head app tracks from the first paint. Measured on four live apps (2026-10-01): create.json mints a guest at Sitecore, sc_cid (Max-Age 730 days, capped to 400 by Chromium) is set by JS, and a VIEW is posted, all before any interaction, with no banner. The SDK has no consent API. Consent is built from the levers it does expose, and this skill wires them end to end:
- No consent → no tracking cookie, no edge-platform beacon, no proxy decision (default variant).
- Consent → tracking, plus personalization if marketing is granted.
- Withdrawal → tracking stops and the tracking cookies are deleted.
Every head app ships this. Consent is a standard acceptance criterion, not an option.
When to use
- Scaffolding or shipping any Content SDK head app.
- Touching
src/Bootstrap.tsx,CdpPageView.tsx, thePersonalizeProxyinsrc/proxy.ts, or anyevent()/identity()call. - Writing the cookie policy, or a test that asserts "no tracking before consent".
Not for: a third-party CMP adapter (the decision is an own first-party banner only), or the personalization decision itself.
Category → SDK switch
| Category | What it switches | Lever |
|---|---|---|
| necessary (always on) | site_consent (this skill), sc_site (multisite routing), sc_bot (bot UAs only) | none: these never carry a visitor identifier |
| functional | app-owned preferences: theme in localStorage, a locale preference the app persists | hasConsentClient('functional') around each write in store code (theme stores are plain functions, not hooks); useAllows('functional') in a component |
| analytics | Bootstrap initContentSdk (analytics + events plugins → create.json, sc_cid), CdpPageView VIEWs, custom events, <Form> events | gate 1 (Bootstrap), gate 2 (CdpPageView + trackEvent) |
| marketing | PersonalizeProxy decision (Edge variantIds lookup + /v1/personalize), proxy-issued sc_cid + sc_cid_personalize, identity() | gate 3 (PersonalizeProxy.skip), trackIdentity |
Marketing requires analytics. initPersonalizeServer hard-codes enableCookie: true and enablePersonalizeCookie: true. Every personalized decision therefore sets sc_cid, the visitor's browser id (not the site's analytics identifier). "Marketing without analytics" cannot be honored, so normalize() makes marketing ⇒ analytics on parse (fail closed), and the banner toggles the pair together.
Consent state contract
One first-party cookie, site_consent, readable by both the proxy (req.cookies) and the client (document.cookie). A consent signal kept only in JS never reaches the proxy. The format is URL-encoded JSON:
{ "v": 1, "pv": "2026-10", "c": { "functional": false, "analytics": true, "marketing": false }, "t": 1759312345000 }
vis the code-levelCONSENT_SCHEMA. Bump it when the category set changes. An oldvreads as no consent everywhere, the proxy included.pvis the authoredPolicyVersionthe visitor answered. A mismatch re-prompts on the client; the previous choices hold until the visitor answers.tis the decision time, kept for the audit trail.- Attributes:
Path=/; SameSite=Lax; Secure; Domain=<hostname minus www>(the same rule Bootstrap uses forsc_cid), so www and apex share one decision. Not HttpOnly.
Template: assets/lib/consent/consent.ts. It is runtime-agnostic, so the proxy, server code and the browser all import it. Client store: assets/lib/consent/consent-store.ts. It uses useSyncExternalStore over the raw cookie string (a stable primitive snapshot), and the server snapshot is '' (no decision). This is the same hydration-safe shape as content-sdk-app-router-theme-hydration-pattern. Place both under src/lib/consent/, never src/components/, which registers everything as a rendering.
The four implementation points
1. Bootstrap: gated init, re-init on grant (assets/sdk/Bootstrap.tsx)
- Gate
initContentSdk, not only the page view. GatingCdpPageViewalone still runscreate.jsonand setssc_cid. A shipped "scope gate" did exactly that: a guest and a 730-day cookie per visitor, with zero views. - Add
analytics(fromuseAllows) to the effect deps. The scaffold effect depends only on[siteName, isPreviewMode]. With a plain gate, a mid-session grant left tracking dead until a hard reload: every soft navigation rejected with[IE-002] SDK not initialized,CdpPageView's.catchswallowed it, and no VIEW was sent (state D, measured). The dep is load-bearing for state B too: during hydrationuseSyncExternalStorereturns the server snapshot ('', no consent), so the first effect pass always skips and the init happens on the post-hydration re-render. Anot initialized: no analytics consentdebug line on every cold load, consented or not, is expected. - Ordering holds by tree position.
<Bootstrap/>is the first sibling insrc/app/[site]/layout.tsx, andinitContentSdkassigns the core context synchronously before its first await. On grant, Bootstrap's effect runs before CdpPageView's effect in the same commit. Keep Bootstrap there, and never under a Suspense boundary.
2. CdpPageView + event helpers (assets/sdk/CdpPageView.tsx, assets/lib/consent/track.ts)
disabled()returnsNODE_ENV === 'development' || !analytics, andanalyticsis in the deps, so a grant sends the current page's VIEW.- All app code sends custom events through
trackEvent(analytics) and identity throughtrackIdentity(marketing, because IDENTITY carries PII). Never importevent()/identity()directly in a component. - That includes the integrated-search starter's
event()call (search-experience/search-components/useEvent.tsx,content-sdk-search). With consent denied: no event andsessionId: ''; the search itself keeps working. <Form>(SDK) subscribes to submit and callsform()with no consent check and no.catch. Without init it raises an unhandled IE-002 and sends nothing; with consent it tracks. The wire behaviour is unmeasured: P7 had no Form component in the test app [probe-gated: P16].
3. PersonalizeProxy.skip reads the cookie (assets/sdk/proxy.personalize-skip.ts)
skip: (req) => !allows(parseConsent(req.cookies.get(CONSENT_COOKIE)?.value), 'marketing'),
skip runs in disabled() before initPersonalizeServer and before the Edge variantIds lookup. A non-consented request therefore gets the default variant, no proxy cookies, and no Edge call (measured: skipped (personalize proxy is disabled) on every request). skip and enabled are the only consent-capable controls: the proxy's cookie flags are hard-coded. Leave BotTrackingProxy ungated, because it acts only on bot UAs.
4. Withdrawal clears the cookies (clearCookies / saveConsent in the store)
- The SDK never deletes
sc_cid. Measured: after withdrawal it survived soft navigations and a hard reload, with its full Max-Age (730 d on the wire, 400 d in Chromium's jar). It also outlives the 180-daysite_consent. - On every save without analytics (not only on a granted → denied transition), delete
sc_cid+sc_cid_personalize(and the legacysc_<contextId>[_personalize]) for host-only, apex,www.<apex>and the full host. Both cookies are JS-set or non-HttpOnly. Onwww, Bootstrap and a proxy-style writer produced twosc_cid(apex + www), so a single-domain delete misses one. A transition-only delete misses the visitor whose consent cookie expired, or whose old-schema cookie now parses as null, whilesc_cidlives on (measured: it survived Reject all). - On a granted → denied transition, then reload. The core exposes only
initContentSdk, with no teardown: an initialized context stays live for<Form>and for the Events module the BYOC bridge hands to components. After the reload, Bootstrap stays gated. - Withdrawing marketing only: delete
sc_cid_personalize, keepsc_cid, no reload. The proxy gate applies on the next request. - Out of reach: the guest already created at Sitecore (erasure goes through a support case),
__cf_bm,sc_site.
The banner (assets/consent-banner/ConsentBanner.tsx)
A Sitecore rendering with one shared datasource, not dictionary entries. Every authored value must arrive on fields, rendered through SDK field components. Dictionary phrases arrive as plain strings, which an author cannot select in Pages. Full content model, placement and comparison: references/banner-content-model.md.
- Fields: Title, Body (Rich Text), PolicyLink, a label and a description for each of the four categories, Accept / Reject / Customize / Save labels, ReopenLabel, and PolicyVersion (shared, not per language).
- Tenant items: clone the JSS Promo bundle (
content-sdk-create-component) intoConsent Banner,Folders/Consent Banner Folder,Rendering Parameters/ConsentBanner Parametersand the renderingConsentBanner, plus aData/Consent Bannercontainer holding the one shared item. Names, field sources, the__Standard Valuesthe clone lacks, the "Promo" display-name trap and the MCP placement recipe:references/banner-content-model.md§ "Building it on the tenant". - Placement: once, in the footer Partial Design. It renders the "Cookie settings" reopen trigger in place and portals the dialog to
document.body. - Default: necessary-only. Nothing is pre-ticked. Reject all is one click, with the same element and style as Accept all.
- Accessible:
role="dialog"witharia-modal="false"on first visit (no trap), labelled by Title and described by Body. Native checkboxes in afieldset. On reopen, focus goes to the heading,Escapecloses, and focus returns to the trigger. - Versioning: bump
PolicyVersionto re-prompt. BumpCONSENT_SCHEMA(code) when categories change. - Hydration: the dialog renders only after hydration (a
useSyncExternalStorehydrated flag). A cached page never ships a server-rendered banner to a visitor who already decided.
Editing and preview
- Pages editing and Design Library: no overlay, no store and no cookie write. The rendering shows a static inline panel with every field, including PolicyVersion, so all of it stays authorable.
- No datasource: the placement arrives with
fieldsabsent. The asset is wrapped in the SDK'swithDatasourceCheck, so editing shows a visible "choose its datasource" placeholder instead of nothing, and normal mode renders nothing. Never ship a bareif (!fields) return null. - Styling: the asset ships no CSS. Unstyled, the dialog is plain flow content, not a banner. The app styles
.consent-bannerwith its own tokens. - Preview: it renders nothing. Bootstrap already skips init when
draftMode()is on, andCdpPageViewskips when!mode.isNormal.
Acceptance test (references/acceptance-test.md, assets/tests/consent-acceptance.spec.ts)
Playwright against next build && next start, with a real Chrome UA. A headless UA is a bot: it sees zero tracking even with the gate removed, so its zero proves nothing. B runs before A (serial pair: A's zero is trusted only after B passed); D and C carry their own positive control, so one failure does not hide the next:
| State | Pass |
|---|---|
| B consent before load | create.json 201 + VIEW 201, then a VIEW 201 per soft navigation |
| A no consent | 0 /v1/events* and /v1/personalize* calls. No sc_cid / sc_cid_personalize. Banner visible |
| D grant mid-session | create.json 201 + VIEW 201 for the current page, with no new document request |
| C withdraw | tracking cookies gone on every domain, then 0 beacons across soft navigations and a reload |
C2 stale sc_cid, no readable consent | Reject all deletes it (no network) |
On a route with personalization variants and marketing consent the guest is minted server-side (Set-Cookie: sc_cid on the document) instead of create.json: assert either, plus VIEW 201 (content-sdk-personalization § verification).
Assert on the tracking names only. sc_site, sc_bot, __cf_bm and site_consent exist regardless, and a literal "zero sc_*" can never pass.
Cookie policy: what the gate cannot reach
references/cookie-inventory.md has the full measured table. Declare these, because no gate fixes them:
__cf_bm: third-party Cloudflare bot management on.sitecorecloud.io, set by Edge media and edge-platform responses, 30 minutes, set with or without consent.sc_site: necessary, HttpOnly, session.sc_bot: bots only.
Hard rules
- Gate init, not just events. No
initContentSdkwithout analytics consent. - Consent lives in a cookie that the proxy can read. localStorage alone is invisible to
PersonalizeProxy.skip. - A grant re-inits without a reload. A withdrawal deletes, then reloads.
- Marketing ⇒ analytics, enforced in the parser, not only in the UI.
- Never trust a zero from a headless UA, a
next devserver, or a run whose positive control (B) did not pass. - Redirect www↔apex at the edge before any tracking. Otherwise the proxy and Bootstrap scope
sc_ciddifferently. - Server-side events from a Route Handler need the same cookie check, and must not call the SDK
event()concurrently: measured, 49 of 50 events went out under another visitor's id.
[probe-gated]
| Item | Gate |
|---|---|
Proxy-issued sc_cid / sc_cid_personalize on a personalized route | MEASURED (P7, probe-findings-s1-p7-2026-10-01.md). With marketing consent, both are set on match and no-match: Max-Age=63072000; Domain=<request hostname>; Secure; SameSite=None, not HttpOnly. Consent denied or no consent cookie: no Set-Cookie, 0 edge-platform calls, default variant. Open: the www-scoped variant on a real www host |
<Form> events: unhandled IE-002 without consent, beacon with consent | P16 (P7 had no Form component) |
| States A–D with these templates: PASS on localhost, production build, the author's own tenant, LIVE context, 2026-10-01. Not yet run on a real www/apex host pair or a deployed app | a deployed run |
Banner from a real Sitecore datasource: template, rendering, Available Renderings, shared datasource, placement, all 17 fields on fields on Edge preview, rendered with authored copy in a production build (real Chrome UA, 0 beacons before consent) | PASS on the author's own tenant, throwaway page, 2026-10-01 |
| Footer Partial Design placement; inline editing in Pages; Design Library mock; the no-datasource placeholder inside Pages | an editing host serving this code (the tenant's editing host does not) |
| Bootstrap ordering under the cache-components template (Suspense around the page) | unresolved |
Related
content-sdk-app-router-theme-hydration-pattern: theuseSyncExternalStorestore shape.content-sdk-app-router-multisite-management: proxy chain order.content-sdk-app-router-editing-safe-rendering,content-sdk-field-usage-image-link-text: banner rendering.content-sdk-component-naming-traps: why helpers stay out ofsrc/components/.
Content SDK troubleshooting (triage hub)
A Content SDK page passes through eight layers before a visitor sees it, and most failures are silent: a 200 with an empty zone, a green build that never starts, a preview that works and a live site that doesn't. This skill does not fix anything itself. It finds the layer, reads that layer's own signal, and hands over to the skill that owns the fix.
Discipline (apply before every step)
- Reproduce first, with the exact surface. Note the URL, environment (local / editing host / preview / live), language and whether you are in Pages. "Broken" on preview and "broken" on live are different bugs.
- Isolate the layer before touching code. Walk the layer table below from the outside in. A layer whose signal is clean is excluded, not suspected.
- Read the raw payload before reading the component. If
layout.sitecore.routeorfieldsis wrong, no amount of JSX change helps (content-sdk-debug-layout-probe). - Every check gets a known-good and a known-bad control. A probe that cannot fail proves nothing: query a route you know works and one you know does not exist, and confirm they differ.
- Assert the first HTTP status, unfollowed.
curl -Lbehind SSO or a login shell follows to a sign-in page and reports 200. Usecurl -sS -o /dev/null -w '%{http_code} %{redirect_url}'. - Preview is the permissive runtime. Route-path forms, media resolution, the 404 page and cache semantics are all looser on preview. A preview pass proves nothing about live; budget one assertion against live.
- Clear the build cache after any CM write (
rm -rf .next) before trusting a build-time read:.sitecore/sites.json, the component map and SSG output are snapshots. - Never print secrets.
DEBUG=content-sdk:editinglogs the real editing secret on a mismatch (sent "…" expected "…"); the revalidate handler and Edge Admin webhook reads echo secrets too. Redact before pasting anything into a ticket, and rotate a secret that reached a log.
Step 1: classify the symptom to a layer
| Symptom | Start at layer | First instrument |
|---|---|---|
| Hydration error, wrong theme flash, dead click, console error | Browser / client | DevTools console + network |
| 404 / 500 locally, wrong site, wrong language, redirect loop | Head-app server + proxy | next dev stdout with DEBUG=content-sdk:* |
| Page 200 but a zone or component empty | Layout payload (Edge) | content-sdk-debug-layout-probe, then Edge GraphQL |
| Works on preview, wrong or 404 on live | Edge preview vs live | the same query on both contexts, side by side |
| Content edited and published, live unchanged | Publishing + cache | publishing job status, webhook lastRuns, ISR window |
| Pages: no chromes, "Preview content is not found", component not found | Editing host + Pages | editing-host RenderingHost log, /api/editing/config status |
| Build or deploy red, or green but never serving | Deploy / build | deployment record + logs, Vercel build log |
| Item missing, template gone, publish fails | CM | CM Log / Publishing files via the Monitoring API |
| Live site not indexed, assets 404, protection wrong | Hosting / delivery | unfollowed HTTP on the live host |
Unsure which row applies? Run the cheapest probe of each of the first four layers in order: console, server log, layout payload, preview-vs-live diff. The first one that disagrees with expectation is your layer.
Step 2: read that layer's signal
Where each log lives, how to fetch it and how to read it: references/log-sources.md. The short form:
| Layer | Where the signal is | Watch for |
|---|---|---|
| Browser | DevTools console + network; localStorage.debug = 'content-sdk:*' for client-side SDK logs | first error, not the cascade; the RSC payload contains the not-found copy on every page |
| Head-app server | next dev / next start stdout; DEBUG=content-sdk:<ns> (17 namespaces, see reference) | content-sdk:http shows every Edge request and its timing |
| Layout payload | /api/layout-debug (temporary), Edge GraphQL layout(site, routePath, language) | route: null = the whole route failed to resolve |
| Editing host | Monitoring API, RenderingHost.* files, listed only under the editing-host environment id | raw stdout, no timestamps |
| CM | Monitoring API, Log.* / Publishing.* per instance and day | match by level; signatures in the log-signatures reference of sitecoreai-health-check |
| Deploy | Deploy deployment record + /api/deployments/v1/{id} | every line is info: read calculatedStatus and *LastFailureMessage, not levels |
| Publishing | Publishing API job status (sitecoreai-publishing) | job done ≠ Edge updated: check the item on Edge |
| Edge → app cache | Edge Admin GET /webhooks/{id} → lastRuns | a 401 from the receiver auto-disables the webhook within seconds |
| Hosting (Vercel) | vercel inspect <url> --logs (build), vercel logs <url> (runtime, live tail ≤ 5 min) | which Edge context id the production env actually carries |
Step 3: pick the instrument that can prove the claim
| Claim | Only this proves it | Never use |
|---|---|---|
| "It is published" | live Edge context read of the item / route | Authoring GraphQL, the preview context, the publish job status |
| "Master is correct" | Authoring GraphQL | Edge in any context |
| "A visitor sees it" | unfollowed HTTP or a real browser on the live host | curl -L, localhost, a Pages screenshot |
| "The app uses the live context" | the hosting environment's variables (vercel env ls), then a live route read with that id | the local .env.local |
| "The editor can author it" | Pages: select the field and change it | a rendered page |
The full instrument table and its traps: sitecoreai-health-check § the four instruments. For a whole-site sweep instead of one symptom, run that skill's doctor.
Step 4: hand over to the owning skill
Known symptom-to-cause pairs, each with the first check and the owning skill: references/symptom-index.md. Routing by layer:
| Layer / topic | Load |
|---|---|
| Pages editing, preview, Design Library | content-sdk-app-router-troubleshoot-editing, content-sdk-app-router-editing-safe-rendering |
Empty or wrong fields, resolver shape | content-sdk-debug-layout-probe, content-sdk-resolver-patterns |
| Component not found / MissingComponent | content-sdk-component-naming-traps, content-sdk-app-router-component-registration |
| Route, 404, placeholders | content-sdk-app-router-route-configuration |
| Proxy, site resolution, redirects | content-sdk-app-router-multisite-management |
| Language, dictionary | content-sdk-app-router-dictionary-and-i18n, sitecoreai-localization |
| Stale after publish, revalidation | content-sdk-app-router-cache-components-and-osr, sitecoreai-edge-admin-webhooks |
| Publish jobs | sitecoreai-publishing |
| Edge query errors, depth, complexity | sitecoreai-edge-graphql-capture, sitecoreai-graphql-schemas |
Serialization, ser pull / push | sitecoreai-serialization, sitecoreai-cli-cloud-workflow |
| Robots, sitemap | content-sdk-app-router-sitemap-robots |
| Variants not shown | content-sdk-personalization, sitecoreai-personalization |
| Tracking, consent | content-sdk-tracking-consent, content-sdk-analytics-events |
| Search UI idle or empty | content-sdk-search, sitecoreai-search-sources |
| Theme flash, hydration | content-sdk-app-router-theme-hydration-pattern |
| After an SDK upgrade | content-sdk-upgrade-assistant |
| Env vars, site config | content-sdk-site-setup-and-env |
| Whole-environment health | sitecoreai-health-check |
Stop conditions
- The fix is a write to a live tenant (publish, republish, webhook re-enable, cache clear, variable change): stop, state the finding with its evidence and let the user run it.
- Do not add variables to an editing-host environment to switch on
DEBUG: the platform injects the app's variables there, and a variable upsert on an editing host has left it unable to roll out, even after the variable was deleted (measured). Reproduce locally against the same context instead. - Reverse drift (master broken, live Edge good): do not republish. A publish would push the broken state live; repair master and verify on preview first.
- Two layers disagree and you cannot say which instrument is wrong: add a control, do not pick the convenient one.
When NOT to use
- A full health sweep of an environment or site:
sitecoreai-health-check. - Building a feature or component: the specialist skills above.
- Pages Router editing specifics: the Pages Router twin of the editing skill, if installed.
Content SDK Upgrade Assistant
Upgrade @sitecore-content-sdk/* packages safely. The procedure is the same for App Router and Pages Router apps — the surfaces most likely to break on a bump are router-specific and each has its own skill (see Hard Rules), so defer to those rather than duplicating router detail here.
Three sources, each seeing what the other two cannot; read all three, in this order. (1) The release notes say what changed inside the packages — behaviour, defaults, reverts — which no file diff can show. (2) The what's-new page defines which package versions constitute "SDK M.m" now that packages version independently. (3) A clean scaffold at the target version is the complete list of OOTB files that changed, new API routes included — the release notes name some of them and omit others, and an agent's memory of "what 2.4 changed" is worse than both. Measured 2026-09-16 on 2.2 → 2.4: the notes named the precedence="high" drop, metadata/OG, the experimental switch and llms.txt, but not the next.config rewrite, getPageMetadata, RouteFields extends PageMetadataFields or the cli bump — the scaffold diff had all of those (10 changed files + 2 new routes) and could not see the getComponentList componentName revert the notes carried.
When to use
- User asks to upgrade SDK packages, update to a new version, or apply a migration.
- Task involves version bumps,
@sitecore-content-sdk/*dependencies, or breaking changes. - User mentions "upgrade," "migration," "new version," or "breaking change."
- An upgrade already landed and someone asks whether it was complete — that is the
--from-gitcase below.
How to perform
- Release notes — the primary source, and NOT
CHANGELOG.md. The repo'sCHANGELOG.mdstops at 2.1.0; since 2.2 every package versions independently and its notes are a GitHub Release per package, indexed by release-notes.html (a version table with links and no content of its own). Read, for the target:create-content-sdk-app@<to>(template-level changes),@sitecore-content-sdk/nextjs@<v>,@sitecore-content-sdk/content@<v>and@sitecore-content-sdk/cli@<v>(behavioural changes; thecliis the component-map generator). URL shape:https://github.com/Sitecore/content-sdk/releases/tag/<package>%40<version>(@encoded);gh api repos/Sitecore/content-sdk/releaseslists them. For a multi-minor jump read every release in between — a 2.2 → 2.4 move inherits everything 2.3 changed. The bodies echo nested dependency updates and Angular items; filter to the app's framework. - What's new — one page per minor crossed.
https://doc.sitecore.com/sai/en/developers/content-sdk/20/what-s-new-in-content-sdk-<M>-<m>.html(deterministic; the page links its siblings). Its value is narrow and real: the package version matrix —core,content,cli,events,analytics-corealongsidenextjs/react/create-content-sdk-app— which is the only place "SDK 2.4" is defined as a set, and the headline list you hand the user. It carries no template changes, no breaking changes and no migration steps (checked 2.3 and 2.4), so it never substitutes for step 1 or 3. Align the app's ranges to that matrix. - Measure the OOTB surface — before touching
package.json:
It scaffolds both references (reused across runs;node scripts/upgrade-surface.mjs --app <head-app> # from = installed minor, to = latest stable node scripts/upgrade-surface.mjs --app <head-app> --to 2.4.0 # pin the target--freshrescaffolds), auto-detects the router (--templateoverrides), and prints one verdict per file on the surface plus the@sitecore*range table. Exit 1 = stale or new-absent findings; exit 2 = the harness could not stand behind a result (scaffold failed, self-check failed). - Work the list, by class.
STALE— the app still has the old OOTB file byte-for-byte: copy the new reference file over it.NEW ABSENT— a route/config the target ships and the app lacks: copy it in, and check for a pairednext.configrewrite or.env*.exampleentry (the script lists those as their own surface files).CUSTOMIZED— the app's copy matches neither reference: the script prints every upstream+/-line with whether it is present in the app (?!marks the unexpected ones). Apply the upstream hunks into the customization by hand, then state a verdict per file — upstream hunks applied / deliberately not applied, because ….?!is advisory:import type { Metadata }vsimport { Metadata }, or spreading...getPageMetadata()under the app's ownalternates, are correct and will flag.REMOVED/APP-DROPPED— upstream deleted a file the app keeps, or the app deleted an OOTB file upstream changed: decide, and record why.!!in the range table — bump every@sitecore-content-sdk/*package to the template's range together, cross-checked against the what's-new matrix from step 2.
- Bump,
npm install,rm -rf .next,npm run build; then apply the behavioural items from step 1 that no file carries, and re-verify the router-specific surfaces (Hard Rules). - Prove the upgrade landed — rerun against the pre-upgrade lockfile, which lives in git now that the working tree is on the new version:
Test editing, preview and the Components Preview page on the editing host after the deploy.node scripts/upgrade-surface.mjs --app <head-app> --from-git HEAD~1 --quiet # exit 0, or the list of what is still missing
Hard Rules
- Never derive the target shape from memory or from the release notes alone. Run the script; the scaffold is the reference (the CLI is run literally, the reference is never hand-written). If
npxcannot reach the registry the upgrade is blocked, not estimated. CHANGELOG.mdis not the changelog. It ends at 2.1.0. Citing it as read for any version ≥ 2.2 is a false claim of having read the notes — the per-package GitHub Releases are the record.- CLI versions are not SDK versions. There is no
create-content-sdk-app@2.2.1;2.3.0/2.3.1/2.3.2all pin^2.3.0,2.4.0pins^2.4.0. The script resolves from as the newest stable CLI release whose template pins the app's installed minor (falling back to the highest release at or below it) and WARNs when the resolved reference does not pin the app's minor — pass--fromexplicitly then. Read the version frompackage-lock.json, never the^range. - Search rides on
nextjs: 2.3 adds facet + locale, 2.4 adds suggest + more-like-this.upgrade-surface.mjsdoes not diff the search API; readpackages/search/CHANGELOG.md(content-sdk-search). 3.0.0-beta.atomsis a sideways move, not an upgrade: since the20261021204512stamp it is stable 2.4.1 plus atoms (earlier stamps forked pre-2.3devand lacked the 2.3/2.4 features), without the 2.5.0-canary changes. Moving onto it means exact beta pins on the whole app (content-sdk-app-router-atoms).- Prefer upgrading all
@sitecore-content-sdk/*packages together to a consistent set unless the user requests a partial upgrade. Check peer dependencies. - After the bump, re-verify the surfaces most likely to be hit using the skill that matches the app's router — App Router and Pages Router diverge on each: the
src/proxy.tschain (content-sdk-{app,pages}-router-multisite-management), the editing path (content-sdk-{app,pages}-router-editing-safe-rendering), the component map(s) (content-sdk-{app,pages}-router-component-registration), and the data flow / static params (content-sdk-{app,pages}-router-graphql-data-fetching,-route-configuration). .agents/,.cursor/,AGENTS.md,CLAUDE.md,Skills.md,README.mdare excluded from the surface by default (--include-docsre-admits them) — they are the CLI's agent-instruction payload, curated separately, and they dwarf the code surface (14 of 26 changed files on 2.2 → 2.4).- Do not edit
.next/,node_modules/, or lockfiles by hand. Do not change CI or root tooling unless the task explicitly includes it. Delete.next/after the bump before any build-reading check — Next's fetch cache survives incremental builds.
Stop Conditions
- Stop if the target version is unclear; run the script with no
--toto see the latest stable and the surface it implies, then ask. - Stop if a
NEW ABSENTroute or aCUSTOMIZEDhunk requires a product or deployment decision (new env var, config schema, a route the editing host will call); list the required changes with the script's output and ask the user to confirm. - Stop if the script exits 2 — a reference that could not be scaffolded is not a reference.
References
scripts/upgrade-surface.mjs— the three-way OOTB diff (dependency-free Node;--jsonfor tooling).- Release notes index → GitHub Releases — per package since 2.2; the repo
CHANGELOG.mdends at 2.1.0. - What's new, one per minor: 2.4 · 2.3 · 2.2 — the version matrix and the headlines.
- Content SDK skills overview.
- Official Content SDK docs.
Content SDK — Variants vs Siblings
When you need a new presentation in Sitecore, you have two options: extend an existing rendering with a new variant, or create a new sibling component (a fresh rendering). This skill says when to pick which, what's shared vs not, and exactly how the SDK resolves a variant at runtime.
When to use
- Adding any new visual treatment for an existing concept (a new Promo style, a new Card layout, a new Hero look).
- Deciding whether to fork an existing rendering or extend it.
- A new variant was added in Sitecore but the head app renders
<MissingComponent>or nothing. - Reading rendering YAML and trying to predict what the React component will receive.
The distinction
| Variant | Sibling component | |
|---|---|---|
| Sitecore rendering item | Same rendering, different FieldNames param | Different rendering item entirely |
componentName in layout response | Same | Different |
Rendering Contents Resolver | Shared (set on the rendering) | Each sibling can have its own |
Datasource Template | Shared | Each sibling can have its own |
Parameters Template | Shared | Each sibling can have its own |
Datasource Location query | Shared | Each can have its own |
ComponentQuery (Integrated GraphQL) | Shared | Each can have its own |
| Author swap cost in Pages | One dropdown click | Remove + add a different rendering |
| Headless Variant item required for author UI | Yes — one per variant | N/A |
| Head-app file convention | <Component>.<VariantName>.tsx, merged into one map entry | Separate folder per component, separate map entry |
What variants are good for
Same data, different presentation. The author picks how this "Promo" should LOOK (Card, Hero, Minimal, Editorial) without changing what content they entered. One Sitecore concept, N visual treatments, swap with one click.
Variants only differ in head-side React representation. Everything else (resolver, templates, queries) is bound at the rendering level and is therefore shared across all variants of that rendering. There is no escape valve — if you need a per-variant resolver or per-variant params, you need siblings.
What forces a sibling (you cannot do this with variants)
Anything that differs at the rendering level forces siblings. Concretely:
- Different
Rendering Contents ResolverGUID → siblings (e.g., the 4-resolver 2×2 family incontent-sdk-resolver-patterns— Datasource Item / Datasource Children / Context Item / Context Children — must be siblings; their resolver classes differ). - Different
Datasource Template(different author-facing field set) → siblings. - Different
Parameters Template(different rendering params) → siblings. - Different
ComponentQuery(Integrated GraphQL) → siblings. - Different
Datasource Locationconstraint → siblings.
Decision rule (heuristic)
Does the new presentation need any of:
- Different fields the author edits? → SIBLING
- Different rendering parameters? → SIBLING
- A different resolver / data shape? → SIBLING
- A different ComponentQuery? → SIBLING
Else (just a different look at the same data)?
→ VARIANT
A third option, beta only: a marketer-composed low-code component (atoms, content-sdk-app-router-atoms). The beta SDK reads lower-case fieldNames, so a Headless Variant authored in Sitecore (FieldNames) never selects a ComponentRef path.
File-side convention (head app)
src/components/Promo_Training/
Promo_Training.tsx # exports `Default` AND `export default Default`
Promo_Training.Fancy.tsx # exports `Fancy` AND `export default Fancy`
Promo_Training.Full.tsx # exports `Full` AND `export default Full`
Promo_Training.Minimal.tsx # exports `Minimal` AND `export default Minimal`
sitecore-tools project component generate-map produces:
import * as Promo_TrainingMinimal from 'src/components/Promo_Training/Promo_Training.Minimal';
import * as Promo_TrainingFull from 'src/components/Promo_Training/Promo_Training.Full';
import * as Promo_TrainingFancy from 'src/components/Promo_Training/Promo_Training.Fancy';
import * as Promo_Training from 'src/components/Promo_Training/Promo_Training';
['Promo_Training', { ...Promo_TrainingMinimal, ...Promo_TrainingFull, ...Promo_TrainingFancy, ...Promo_Training }]
All variant exports merge into one map entry keyed by componentName. The merged object carries:
- Named exports for each variant (
Default,Fancy,Full,Minimal) - A single
default(the last-spread module'sexport default— i.e., the mainPromo_Training.tsx)
SDK-verified resolution flow (the runtime contract)
From @sitecore-content-sdk/react/dist/cjs/components/Placeholder/placeholder-utils.js:
const exportName = renderingDefinition.params?.FieldNames;
const renderedComponent =
exportName && exportName !== 'Default'
? component[exportName] // (A) named-export lookup
: component.default || component.Default || component; // (B) default fallback chain
if (!renderedComponent) {
logUnknownComponentError(...);
return <MissingComponent />;
}
FieldNames value | Path | What renders |
|---|---|---|
undefined / missing | (B) | component.default → component.Default → component |
"" (empty string) | (B) | Same as above (falsy) |
"Default" (literal) | (B) | Same as above — does NOT try component.Default via path A |
"Fancy" (exact, case-sensitive) | (A) | component.Fancy if it exists |
"fancy" (wrong case) | (A) | undefined → <MissingComponent> + console warning |
| Any value with no matching export | (A) | undefined → <MissingComponent> + console warning |
Three things to remember:
- Case-sensitive.
FieldNamesvalue must match the export name exactly (Fancy≠fancy). - Empty/missing is safe in the SDK, and not always in the CM. The SDK falls back to the default export. But once the rendering has any Headless Variant item, the Layout Service resolves a missing
FieldNamesto the alphabetically first variant, before the head app sees it (§ Authoring side). - Wrong name is loud, not silent — visible
<MissingComponent>placeholder + console warning.
Authoring side — Headless Variant items are required for the dropdown
To make a variant available to authors via the Pages dropdown, you MUST create a Headless Variant item in the CMS:
/sitecore/content/<tenant>/<site>/Presentation/Headless Variants/<Rendering>/<VariantName>
Example: /sitecore/content/dog-feeding/training/Presentation/Headless Variants/Promo_Training/Fancy
- These items are manually created in the CMS — they are not auto-generated from the head-app
.tsxfiles. - The item name (e.g.
Fancy) becomes theFieldNamesvalue when the author selects it. - Without a Headless Variant item, the variant cannot be selected in Pages — even if the export exists in the head app.
- Without a matching
.tsxexport, the dropdown still shows the variant but selecting it renders<MissingComponent>.
The two sides must stay in sync. Adding a variant is a two-step operation: head-app .tsx file + CMS Headless Variant item. Either one alone is broken.
Writing a placement raw (measured 2026-09-27 → 28)
Pages writes these values for you. A script writing __Renderings XML over Authoring GraphQL has to get three things right, and a mistake in any of them silently renders the wrong variant:
FieldNamesins:paris the variant ITEM's GUID, braced and dashed:s:par="FieldNames={0A1B2C3D-4E5F-4A6B-8C7D-9E0F1A2B3C4D}". The Layout Service turns it into the item's name before it reaches the head app, so the SDK contract above is unchanged. A literal name (FieldNames=Light) resolved to the alphabetically first variant (Basic), with no error.- Create an explicit
DefaultHeadless Variant item once any sibling variant exists, and reference its GUID. Without that item, an omittedFieldNamesmeans "first child", not"Default"."Default"resolves only on a rendering with no variant items. - Every other parameter needs its own
key=valuetoken (FieldNames={GUID}&HeadlineStyle=eyebrow). A save can also rewrites:paras bare, valueless tokens (GridParameters&FieldNames&Styles&…), and one such placement resolved to a non-default variant. Remove bare tokens.
After any raw placement write, read params back through the layout (content-sdk-debug-layout-probe, or a direct Edge layout query). The page builds, renders and passes review with the wrong variant, so reading params back is the only check that catches it.
Hard Rules
- Variants share EVERYTHING rendering-side. No exception — if you find yourself needing per-variant params or per-variant resolvers, you're choosing the wrong tool and must use siblings instead.
FieldNamesvalue === React export name, case-sensitive. No casing normalization, no fuzzy match.- Variant addition is two-step: create
.tsxexport AND create Headless Variant item. Missing either side breaks one of two failure paths (no dropdown vs MissingComponent). - gen-map merges variants into ONE map entry. Don't try to register variants as separate map keys — gen-map will produce the wrong structure and
componentName-based lookup will miss. - Main file (
<Component>.tsx) is spread LAST in gen-map output, so itsexport defaultwins ascomponent.default. Keep the main file's default export as the "Default" variant for safe fallback behavior. FieldNames="Default"triggers the fallback chain, not a named lookup. Don't accidentally rely oncomponent.Defaultbeing picked via path A — it's only picked via path B (as the second link aftercomponent.default).- For a clean sibling, create a separate folder with its own
componentNamematching the rendering item exactly (seecontent-sdk-component-naming-traps).
Stop Conditions
- Stop and ask if the user describes a new presentation that needs different fields/params/resolver — that's a sibling, not a variant; confirm before scaffolding.
- Don't add a variant
.tsxwithout also creating the CMS Headless Variant item (or telling the user they need to). The variant will silently not appear in Pages. - Don't add a CMS Headless Variant item without a matching
.tsxexport — production will render<MissingComponent>for that variant. - Don't switch a sibling to a variant just because "they look similar" — verify the rendering items would actually share resolver/templates/params first. Forcing a merge fights Sitecore and produces brittle author UX.
Verification
- After adding a variant, the regenerated
.sitecore/component-map.tsshould have the variant's import alias added alongside the others, and they should all merge into the samecomponentNamemap entry. - Set
FieldNamesto the variant name in Pages → the head app should render the variant's component. - Set
FieldNamesto a deliberately wrong name → the head app should render<MissingComponent>and log a warning to console (proves the resolution flow is wired right). - Clear
FieldNamesentirely → the head app should render the default variant (the main file's export). On a rendering with Headless Variant items, assert that the resolvedparams.FieldNamesisDefaultand not the first variant alphabetically.
Related
content-sdk-app-router-component-scaffold— for the underlying file-structure rules.content-sdk-app-router-component-variants— generic SDK guidance on variants; this skill is the playground-derived, runtime-verified deep dive.content-sdk-component-naming-traps— folder/file naming for components AND variants.content-sdk-resolver-patterns— the resolver-level distinctions that often force sibling vs variant choices.
References
- SDK resolution source:
@sitecore-content-sdk/react/dist/cjs/components/Placeholder/placeholder-utils.js(function that resolvesFieldNamesto an export). DEFAULT_EXPORT_NAMEconstant:@sitecore-content-sdk/react/dist/cjs/components/sharedTypes/components.js="Default".- Captured example: a
Promocomponent with four variants (Default, Fancy, Full, Minimal) and the four matching Headless Variant items under the site'sPresentation/Headless Variants/Promo/; the file convention and the resolution behaviour above are transcribed from that run.
Content SDK Website Build — domain craft
Reusable Sitecore/CMS/head-app recipes for Content SDK websites. Not a pipeline playbook: stage order, slash-commands, and agent roles belong to the calling project.
Most failures come from desyncing two tracks. Keep them honest at every handoff.
The two-track model
| CMS track (live tenant) | Head-app track (repo) | |
|---|---|---|
| Artifacts | Renderings, parameters/datasource templates, Headless Variants, content items, site collection / site nodes, publish events | Components, queries, route handlers, theme, chrome, build output |
| Source of truth | Live tenant (*.sitecorecloud.io); authoring solution mirrored via ser pull | Head-app repo (editing host) |
| Sync | Author live (to preview); dotnet sitecore ser pull into the CM authoring solution — never push | Port / implement against live Edge payloads |
Items are authored live and pulled into the CM code base. Publishing to LIVE Edge is a separate, explicit step — during build/author work, rely on preview.
NEW vs EXISTING (content-model direction)
Ask once up front. It drives whether the content model is derived or read.
| Scenario | Content model | Static reference app (optional) | Provisioning shape |
|---|---|---|---|
| NEW site | Derived from design / static props / clickdummy; authored live during implementation | Built before the head app if used; props chosen freely | Full cascade: project → CM env → editing host → collection → site; create CM baseline when the CM is new |
| EXISTING site | Already exists — inventory first (templates, datasource field types, renderings, resolvers) | If used, props bounded by inventoried field shapes | Create only missing rungs (often editing host + head-app scaffold); reuse existing CM code path |
Incremental addition of one rendering to an already-built head app: skip any separate static app; use the per-component cycle directly.
Build-directly vs separate static app
The separate static app (plain Next.js, zero @sitecore-content-sdk/*) decouples UI from the tenant. It is not free: components are written twice (plain props, then ported to SDK fields).
| Situation | Approach |
|---|---|
| Tenant provisioned + visual design / clickdummy approved | Build directly in the head app (default). Clickdummy is the visual oracle; preview each component against the live tenant |
| No tenant yet / offline / design still fluid / want a tenant-independent UI artifact | Produce the separate static app, then port |
| Incremental addition to an already-built head app | Per-component cycle directly (no static app) |
When building directly, the "port loop" collapses to: implement with SDK field components in the head app, clickdummy as visual oracle — same checklist, minus copy-from-static.
Why prefer a real tenant over mocking
Content SDK reaches Edge from getPage, getDictionary, getErrorPage, generateStaticParams, and the sitecore-tools:build prelude. Mocking "no tenant" metastasizes into sentinel guards across many files plus a fragile npm run dev. A real tenant keeps the head app stock; the port (or direct build) is where Sitecore expertise is applied against real payloads.
Mock data is an explicit OPT-IN, never the default. See Appendix.
CM ↔ editing-host deploy ordering
- Deploy the CM first (
cloud deployment create … --upload --working-dir <cm>/ --no-watch). The deployment creates the Edge resource for the env contextId early in the run. - Wait ~1–2 minutes (or poll until past Edge-resource creation) before deploying the editing host.
- Deploy the editing host (
cloud editinghost deploy … --upload --working-dir <head-app>/ --no-watch).
The EH next build SSG-prerenders against Edge at build time. Concurrent CM+EH deploy yields the sitecoreContextId does not contain a edge resource. Empty content is fine; the Edge resource must exist first.
Auth gotcha (XM Apps writes): mint a CM environment automation client (POST /api/clients/v1/cm) after CM deploy. Collection/site creates need that minted token — the org deploy-admin token 401s on those writes.
RenderingHost: after the editing host is up, set the Site Grouping item field RenderingHost (plain string) to the renderingHosts.<key> name from the head app's xmcloud.build.json (must match the editing-host name). Path: /sitecore/content/<COLLECTION>/<SITE>/Settings/Site Grouping/<SITE>.
{ item(where: { path: "/sitecore/content/<COLLECTION>/<SITE>/Settings/Site Grouping/<SITE>", language: "en" }) {
itemId(format: D)
field(name: "RenderingHost") { value }
} }
mutation SetRH($id: ID!, $name: String!) {
updateItem(input: { itemId: $id, language: "en", version: 1, fields: [{ name: "RenderingHost", value: $name }] }) {
item { field(name: "RenderingHost") { value } }
}
}
Page / Partial Designs — site chrome skeleton
When SitecoreAI creates a site it provisions empty Presentation/Page Designs and Presentation/Partial Designs. Populate the minimum chrome skeleton once per site (idempotent).
Auth: CM environment client JWT. Endpoint: https://<tenant>.sitecorecloud.io/sitecore/api/authoring/graphql/v1
Template IDs (stable across tenants in the same org — still verify if unsure)
- Partial Design:
{FD2059FD-6043-4DFE-8C04-E2437CE87634} - Page Design:
{1105B8F8-1E00-426B-BF1F-C840742D827B}
createItem requires braced {GUID} for templateId.
Step 1 — Idempotency check
{
headerPD: item(where: { path: "/sitecore/content/<COLLECTION>/<SITE>/Presentation/Partial Designs/Header", language: "en" }) { itemId(format: D) name }
footerPD: item(where: { path: "/sitecore/content/<COLLECTION>/<SITE>/Presentation/Partial Designs/Footer", language: "en" }) { itemId(format: D) name }
pageDesign: item(where: { path: "/sitecore/content/<COLLECTION>/<SITE>/Presentation/Page Designs/Page", language: "en" }) { itemId(format: D) name }
}
Non-null → skip that create. All three present → skip to wiring (or stop if chrome renderings not ready yet).
Step 2 — Create Partial Designs
mutation {
headerPD: createItem(input: {
name: "Header"
templateId: "{FD2059FD-6043-4DFE-8C04-E2437CE87634}"
parent: "/sitecore/content/<COLLECTION>/<SITE>/Presentation/Partial Designs"
language: "en"
}) { item { itemId(format: D) path } }
footerPD: createItem(input: {
name: "Footer"
templateId: "{FD2059FD-6043-4DFE-8C04-E2437CE87634}"
parent: "/sitecore/content/<COLLECTION>/<SITE>/Presentation/Partial Designs"
language: "en"
}) { item { itemId(format: D) path } }
}
Step 3 — Create Page Design and link partials
mutation {
createItem(input: {
name: "Page"
templateId: "{1105B8F8-1E00-426B-BF1F-C840742D827B}"
parent: "/sitecore/content/<COLLECTION>/<SITE>/Presentation/Page Designs"
language: "en"
}) { item { itemId(format: D) path } }
}
Then set PartialDesigns (no space in field name; pipe-separated braced GUIDs):
mutation {
updateItem(input: {
itemId: "{<PAGE-DESIGN-ID>}"
language: "en"
version: 1
fields: [{ name: "PartialDesigns", value: "{<HEADER-PD-ID>}|{<FOOTER-PD-ID>}" }]
}) { item { field(name: "PartialDesigns") { value } } }
}
Assert: PartialDesigns is non-empty before treating chrome structure as done.
Step 4 — Wire Header/Footer renderings into partials
Run only after Header and Footer React components are ported and their rendering items exist in the CM. Structure (steps 1–3) can complete earlier; placement is a one-shot close-out.
Resolve rendering IDs:
{
header: item(where: { path: "/sitecore/layout/Renderings/Project/<COLLECTION>/Header", language: "en" }) { itemId(format: D) }
footer: item(where: { path: "/sitecore/layout/Renderings/Project/<COLLECTION>/Footer", language: "en" }) { itemId(format: D) }
}
Update __Renderings on each Partial Design. Always pass the XML via GraphQL variables — inline strings containing / cause EXEC_SYNTAX_ERROR.
mutation UpdateRenderings($itemId: ID!, $xml: String!) {
updateItem(input: {
itemId: $itemId
language: "en"
version: 1
fields: [{ name: "__Renderings", value: $xml }]
}) { item { field(name: "__Renderings") { value } } }
}
Header PD variables (fresh GUID for uid):
{
"itemId": "{<HEADER-PD-ID>}",
"xml": "<r xmlns:p=\"p\" xmlns:s=\"s\" p:p=\"1\"><d id=\"{FE5D7FDF-89C0-4D99-9AA3-B5FBD009C9F3}\" l=\"{96E5F4BA-A2CF-4A4C-A4E7-64DA88226362}\"><r uid=\"{<NEW-GUID>}\" s:id=\"{<HEADER-RENDERING-ID>}\" s:ph=\"headless-header\" s:ds=\"\" s:par=\"\" /></d></r>"
}
Footer PD: same shape with s:ph=\"headless-footer\" and the footer rendering id.
| Constant | Value |
|---|---|
| Default layout device ID | {FE5D7FDF-89C0-4D99-9AA3-B5FBD009C9F3} |
| Default layout ID | {96E5F4BA-A2CF-4A4C-A4E7-64DA88226362} |
| Header placeholder | headless-header |
| Footer placeholder | headless-footer |
After this, Pages shows Header + Footer on every page using the Page Design — without per-page chrome authoring.
Assigning the design to a route by its Page Design field? Write the id braced, dashed and uppercase ({0A1B2C3D-4E5F-4A6B-8C7D-9E0F1A2B3C4D}, never {0a1b2c3d4e5f4a6b8c7d9e0f1a2b3c4d}). An undashed value is accepted and reads back fine, but the design merge cannot resolve it: headless-header and headless-footer come back as [] on Edge and in edit mode, with no error. An empty shell looks the same whether the merge worked or not, so assert that a chrome rendering actually arrives (measured 2026-09-26). More write-side wire formats are tabled in content-sdk-create-component (its GraphQL-sequence reference, § "Write-side wire formats").
Per-page variation of a chrome block
A chrome block that must sit in the chrome but vary per page (a footer CTA whose headline changes by section, for example) has one working shape. Measured 2026-09-28 → 29:
- Keep the rendering on the Partial Design. Its datasource is the default.
- Add a page-level
Droplinkoverride field on the page template's content section (e.g.Footer CTA). Source it to the small set of global variant datasources (query:$site/*[@@name='Data']/*[@@templatename='<Block>']). - Resolve it server-side in the component. If the route's field resolves to an item with non-empty
fields, render those fields instead of the partial's. Otherwise fall back to the partial's datasource. The override's own fields arrive inroute.fields['<Field>'].fieldsas realFieldobjects, so they render through the same SDK field components and stay inline-editable. Only children the override needs (rows) take a server-sideclient.getData.
Two shapes that fail:
- Placing the block per page in
headless-mainmoves it inside<main>, above the page's last section, and breaks the visual contract. - Adding a new page-level placeholder (e.g.
headless-footer-pagein the layout's<footer>) does not work either. The Layout Service silently drops a placeholder key that is not registered: it is missing fromroute.placeholders, and the head app logs only "Placeholder '…' was not found in the current rendering data".
Content-model spec (from design / static props)
Derive a site content-model document mechanically:
- One prop / design field → one datasource field (SDK type from usage: headline → Single-Line Text, HTML → Rich Text,
<img>→ Image,<a>→ General Link) - Pages → placeholders + rendering placements
- Keep each component's prop boundary as one flat object mapping 1:1 to a future datasource
Author that model live via Authoring GraphQL (or clone OOTB renderings — see content-sdk-create-component) so items are visible on Preview Edge; defer LIVE publish.
Dependency order for hand or API authoring:
- Site collection / site nodes (often created at provision time via XM Apps API)
- Datasource templates → parameters templates → rendering items (
componentNameexact) - Available Renderings → page presentation → datasource content → Headless Variants
- Publish → separate LIVE step
Avoid generic parameter names (Levels, Depth, Style, Items) — they collide with base templates; prefer Level or namespaced names.
Port transform (static or clickdummy → Sitecore component)
Per rendering:
- Place markup in
src/components/<Component>/<Component>.tsx(helpers go insrc/lib/<feature>/orsrc/app/api/<feature>/— seecontent-sdk-component-naming-traps). - Replace plain props with SDK field components:
<Text>,<RichText>,<Image>,<Link>— types fromnode_modules/@sitecore-content-sdk/react.d.ts. - Derive props from the live
getPage/ layout-debug payload, not from static prop names alone. - Classify resolver pattern (
content-sdk-resolver-patterns); decide variant vs sibling (content-sdk-variants-vs-siblings). - Regenerate component map; lint +
tscclean; confirm on preview; re-probe payload.
Risks: wrong resolver → blank render; componentName typo → <MissingComponent>; helpers under src/components/<X>/ → polluted map; treating empty-state field shapes as populated → null deref; port drift from static names.
Client-triggered reads: Route Handler under src/app/api/…, never a Server Action (content-sdk-app-router-route-handler-vs-server-action).
Cross-cutting domain rules
- Tracks sync at handoffs — do not claim head-app work is done against live data without matching CMS state on preview (or LIVE after an explicit publish).
- Probe before implementing (
layout-debug/ resolver probe). - Dark+light+system theme is the default head-app theme stack (
content-sdk-app-router-theme-hydration-pattern). - Never silently fail on an unexpected Edge shape — capture the payload and escalate.
- CM env is 1:1 with a CM authoring code base — create a new baseline only for a new CM; for an existing CM, reuse its code base at the path the user gives.
- Pull-on-ship for structural items; pull authored content after LIVE publish — never push.
Gate the PR preview deployment
A head app has a defect class that no local gate can see: the component map, the layout data and
the rendering definitions live in three different systems, and only a rendered page proves they
agree. Lint, unit tests and the build all pass while a component resolves to the SDK's
MissingComponent placeholder on every page of a live site. Measured 2026-09-01: an SDK bump
regenerated one map key, the nav vanished site-wide, and 814 unit tests, lint, the build and the
SSG route count were all green.
The precondition — check it before trusting the gate. A preview deployment is only an honest
predictor of production if it resolves the same Edge context production will. On one measured estate the
Vercel Preview target deliberately carries the LIVE context id (not the preview one), so it
does. Verify for your project — vercel env pull <scratch> --environment=preview — because if
Preview points at the preview context instead, the deployment serves unpublished content at a
live-looking URL and a green smoke proves nothing about production.
Corollary, worth socialising: with the live context, the preview URL cannot show unpublished content. It is a production-fidelity gate, not a content preview surface.
Assert structure, never pixels. On a CMS-backed site the copy and imagery change independently of the code, so a pixel diff fires on every author edit; the gate then gets ignored, taking real regressions with it. Assert what holds regardless of what an author writes:
- no
missing React implementationtext on any route ← the reconciliation - every route returns 200, and the final URL is still on the deployment origin
nav/main/footerpresent; nav carries real links, not allhref="/"- no console errors (filter third-party beacons, or it will be flaky and then ignored)
Harness notes. Use a SEPARATE Playwright config with no webServer block — this suite runs
against a remote URL, and a reuseExistingServer here can adopt a sibling head app on the same port
and pass confidently for the wrong site. Make the base URL required and throw when it is missing
rather than defaulting to localhost; a smoke suite that silently retargets is a check that cannot
fail. Trigger on the platform's deployment_status-style event, not on PR open — the URL does not
exist until the build finishes.
Two false-pass shapes this must survive:
- Vercel SSO returns a plausible 200 at the end of a redirect to
vercel.com. Bare deployment URLs sit behind deployment protection; only the production alias is public. Assert the final origin, not just the status — otherwise a protected deployment reads as a healthy one. - A stale static page. Correct Edge data does not mean a correct site: SSG routes with no
revalidatenever refresh, so a page can serve build-time HTML indefinitely (x-vercel-cache: HIT,x-nextjs-prerender: 1) while Edge is already right. Smoke the new deployment, and do not conclude "published ⇒ visible".
Prove the gate fails before trusting it. Plant a real mismatch — build with a component key the CM does not have, serve it, and confirm the smoke goes red. A gate nobody has watched fail is not a gate.
Appendix: mock-data opt-in (NOT the default)
Only when the user explicitly asks to build with no tenant. Contain mocks to one seam:
- One
getLayout(path)(or equivalent) module returning fixtures today /client.getPagetomorrow. - Fixtures shaped as declared Layout types (cite
.d.ts). - Quarantine Edge-side SDK calls (
getDictionary,getErrorPage, static params) behind one flag in that module. - Document that
npm run dev/sitecore-tools:buildstill hits Edge unless an offline script exists. - Still produce the content-model spec — mock defers provisioning/authoring, it does not cancel it.
Related skills
setup-content-sdk— head-app scaffold + envsitecoreai-cli-cloud-workflow— CLI login / ser pullcontent-sdk-create-component— clone/customize renderings via Authoring GraphQLsitecoreai-edge-graphql-capture— Edge snapshotcontent-sdk-resolver-patterns,content-sdk-debug-layout-probe,content-sdk-component-naming-traps,content-sdk-variants-vs-siblings,content-sdk-app-router-component-level-navigation,content-sdk-app-router-theme-hydration-pattern,content-sdk-app-router-route-handler-vs-server-action,content-sdk-playground-pattern
Sponsors
Details
- Marketplace
- Chris1415/sitecore-skills-pocs
- Source
- plugins/sitecore-content-sdk
- Category
- Sitecore
- License
- Apache-2.0