Chris1415 avatar

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-pocs

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Chris1415/sitecore-skills-pocs.

Contents

Discovered from source

Skills 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.tsx or 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). Use content-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

PieceWhere (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 ScriptspageView({channel, currency, page, pageVariantId, language}) once per route, only when mode.isNormal
BotTrackingProxysrc/proxy.ts, second, after previewBot 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 analyticsPlugin before eventsPlugin.
  • Context ids. The browser uses config.api.edge.clientContextId, which defaults to NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID and is inlined into the public bundle. The server uses config.api.edge.contextId (SITECORE_EDGE_CONTEXT_ID). defineConfig has 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.contextId and 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 no LocaleProxy. Otherwise the same rules apply.

2. Pick the event

EventAPI (@sitecore-content-sdk/events)Wire typeSend fromUse it for
Page viewpageView(data?: PageViewData)VIEW (the dashboard shows it as "pageView")Client, through the scaffold's CdpPageView onlyEvery normal page render. pageVariantId ties the view to a personalization or A/B variant
Customevent(data: EventData)your type stringClient by defaultInteractions and conversions
Formform(formId, 'VIEWED' | 'SUBMITTED', componentInstanceId)FORMClient, automatic through the SDK <Form> componentSitecore Forms. Never hand-wire it
Identityidentity(data: IdentityData)IDENTITYClient 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 viewbotPageView({page, language, userAgent})VIEW, channel:'bot'Server, inside BotTrackingProxy onlyCrawler 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 to pageView, event and identity.
  • identity: identifiers: [{id, provider}] is required (MV-003). dob is date-only YYYY-MM-DD (IV-003) from events 2.1.2 on. identifier.expiryDate must be a full ISO date-time (IV-005). email is validated (IV-004). The beta.atoms builds predate 2.1.2 and reject a date-only dob.
  • pageView reads the referrer only on the first view per page load (static isFirstPageView). includeUTMParameters defaults to true.
  • Set currency from 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. The getClientId() 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. pageView skips bots, but event() and identity() do not. A bot has no sc_cid, so the event goes out with browser_id: "" and is rejected (404 or 400 observed), swallowed as null. sc_bot is 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.isNormal before calling, as CdpPageView does.
  • Exit clicks. sendEvent uses fetch with no keepalive, 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 stayed pending when 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 (await trackEvent with a ~300 ms timeout, then location.assign), or queue via @sitecore-content-sdk/events/browser and flush on the visitor's next page (only if they return). A redirecting form submit is unmeasured [probe-gated: P16].
  • The ./browser queue. addToEventQueue / processEventQueue from @sitecore-content-sdk/events/browser batch 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.tsx passes the whole events module to BYOC components (FEAAS.setContextProperties({ eventsSDK: Events })). A BYOC component's eventsSDK.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:

  1. It runs in a Route Handler, with the carrier pattern. Give analyticsProxyAdapter(req, carrier) a new NextResponse(null) as the carrier, then copy carrier.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's sc_cid is lost. RSC cannot set cookies at all. The full code is in references/server-events.md.
  2. Pass page, language and referrer explicitly. Server-side they default to an empty string or null.
  3. Bot UAs fail silently. The adapter skips create.json for bots, so the event goes out with browser_id: "", gets a 400, and event() resolves null without throwing.
  4. No concurrency. This is a live limitation (T15). initContentSdk overwrites a process-global singleton, and event() 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's browser_id, and edge-platform answered 201 to all 50. Without jitter it was 24 of 50. Set-Cookie stayed correct per request, so nothing in the response reveals the mis-attribution. Until Sitecore fixes the singleton, a per-request initContentSdk on the server is safe only when calls are serialized per process. The escape hatch is a direct POST with the request's own sc_cid and no SDK state (references/server-events.md). The same singleton runs inside PersonalizeProxy and BotTrackingProxy; whether the proxy path cross-contaminates is [probe-gated: P22].
  5. 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 example ACME_NEWSLETTER_SIGNUP or ACME_PDP_ADD_TO_CART. The SDK's own JSDoc suggests site:ACTION. Pick one form per estate and never mix them.
  • Never reuse reserved or standard names: VIEW, IDENTITY, FORM, the legacy CDP names ADD, SEARCH, TRACKING, INTERACTION, anything starting SC_ (SC_SEARCH_WIDGET_VIEW / _CLICK belong to Sitecore Search), and the display label pageView. 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' with core: { componentId, componentInstanceId, interactionType, keyword, nullResults } feeds the search dashboard (content-sdk-search). It is distinct from standalone Search's SC_SEARCH_WIDGET_* and from the reserved uppercase legacy SEARCH. Case sensitivity [probe-gated: P7].
  • Keep type stable. The dashboard groups by the string, so a rename starts a new row. Put variable data in extensionData, never in type.
  • Tag synthetic traffic. Probes and tests use a <SITE>_PROBE_* type or extensionData.probe_tag, so they can be filtered out of live dashboards.

6. Suppression: who sends nothing, and why

ContextBootstrap initCdpPageViewCustom helper (§ 3)<Form>BotTrackingProxy
next devoffoffno-op (IE-002)fires, unhandled IE-002 [probe-gated: P16]off
Pages editing / preview (draftMode)offoff (!mode.isNormal)no-opoff in editingskips preview
Bot UA (isbot)inits, but no sc_cidskipped ("visitor is a bot")no-op (sc_bot)skippedsets sc_bot, sends botPageView
Headless browser (Playwright default, HeadlessChrome, curl)treated as a botskippedno-opskippedsc_bot (not on localhost)
localhost production buildononononskipped, unless SITECORE_ENABLE_BOT_TRACKING=true
No consentoff (via the consent skill)offno-opsee the consent skillunaffected (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.

  1. Use a production build against the LIVE context (next build && next start, or the deployment). Dev and preview send nothing.
  2. 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.
  3. Assert the positive control first: GET …/browser/create.json returns 201 and sc_cid is set. Only then trust a count.
  4. Assert the beacon: POST …/v1/events/v1.2/events returns 201 {"status":"OK","ref":…}, and the request body type is your name.
  5. Read a failure from its body. A 404 is either No sitecore context (wrong or missing context id) or Invalid browser id/ref specified (missing or unknown sc_cid). siteId is not validated: a bogus site also gets 201, so it is not a negative control. Use a bogus context id instead.
  6. Check the server side. Run with DEBUG=content-sdk:events (or the fetch tap in references/testing.md); the events log includes the response status.
  7. Check ingestion. In SitecoreAI, open Performance → Events. Custom events are listed by type, with event and session counts, next to pageView. Ingestion latency, and whether IDENTITY and FORM show up there and in Profiles, are [probe-gated: P10].
  8. 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: siteId is 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 ungated initContentSdk or a direct event() 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 to BotTrackingProxy. Do not double-send them.
  • Validate locally what the SDK validates: 50 ext attributes, identifiers present, date-only dob.
  • 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_cid or 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.ts paths, 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.atoms dist-tag only, exact pins, React only). Check content-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.

VerdictMeaningTypical members
low-code-candidateOnly authored fields + static markup + param/variant stylingContent block, rich text, promo without logic, simple CTA, quote, stat
partialComposable core with something a Document cannot do: a list over datasource children, route-context fields, structured data, editing-only branches, sizeCard lists, title with route fallback, promo with JSON-LD
keep-codeData fetching, client state, event handlers, forms, placeholders, personalizationNavigation, 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:

  1. 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.
  2. 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.
  3. 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.
  4. Editing behaviour. Does it branch on page.mode.isEditing to 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.
  5. Dictionary / i18n labels. Fixed microcopy from the Sitecore Dictionary or next-intl has no binding in a Document. Move it to a field or keep code.
  6. 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's Container is 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:

  1. 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.
  2. New rendering, same datasource. Create a rendering on the CM's Hosted JSON Rendering template with its ComponentRef pointing at the Document path; keep the old code rendering available.
  3. Compose the Document in Design Studio (by hand only against a mock MMS) reproducing the current look; variants become further Documents (<default>|<Variant> refs).
  4. 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-code on this tenant? Read the editing host's runtime log for the mode. On one test environment on 2026-11-03 (stamp 20261021204512, six atoms, lock passing, site bound to a running editing host) the editing host's log showed 30 Design Library sessions, all mode library, none library-low-code, and a Design Studio draft component opened with no ComponentRef, 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. partial components as hybrids (code container, low-code items).
  • Never. keep-code.

5. Report

Write atomic-design-assessment.md with:

  1. Context: app, SDK version, router, component count, the § 0 framing and whether Design Studio low-code is available.
  2. Verdict table: component, scanner verdict, final verdict, reason, variants, monthly change demand (if known).
  3. Proposed atom set: atom, kind (leaf / container), props (fields + enums), covers which components, Content Kit or custom.
  4. Token decisions the atoms freeze (spacing, tone, type scale), with open questions for the design owner.
  5. Migration waves, with Wave 0's probe questions explicit.
  6. 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).
  7. 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

ClassWho authors the rows, whereExamplesShapeDeliveryEditable in Pages
A. Owned rowsThe author of this component, heretabs, accordion panels, stats, a hand-made card rowContainer datasource with row childrenRendering ComponentQuery, every field as jsonValueYes: row fields inline and reorder (confirmed in Pages 2026-11-04); add and delete through Manage items
B. Derived viewSomeone else, on other pageslatest news, child-page lists, sibling menusNo datasource rows; the source pagesServer-side Edge fetch, cached, revalidated on publishNo, by design: an "edit at source" link in editing mode
C. Curated referenceThis author picks; the items live elsewherefeatured products, shared slidesMultilist / Treelist field on the datasourceThe field itself (items arrive in layout data)Picking and ordering yes; the picked items' fields are edited at their source
D. Shared libraryA team, in one folder, used by many componentsclient logos, team members, 100+ itemsFolder with insert options, no rows in layout dataIds first, then fetch the subset shownThrough 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 ComponentQuery holds about 14 to 21 rows by field count; a server fetch with url about 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

  1. ComponentQuery on the rendering with jsonValue fields (class A). It returns the container fields and the children in one payload; jsonValue keeps them editable. It replaces the whole fields payload, so select everything the component renders. Clear the rendering's resolver: a resolver set alongside a query won in our projects [measured, not documented].
  2. Server-side Edge fetch (classes B and D) through the SDK client (client.getData) in a server component. It pages freely (cursor, variable first), has no republish dependency and needs caching plus revalidation. No editing metadata, so it is only for rows authored elsewhere.
  3. Multilist / Treelist field (class C). The picked items arrive whole in layout data, so cost grows with their fields.
  4. 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 url and every named field per child. A ComponentQuery row past children(first: N) is dropped without an error; a query over budget arrives as isContentResolved: false. Size first above 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 ComponentQuery list 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 name selection, 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 __Sortorder in 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

  1. 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's children.total (silent drop), flags rows not selected as jsonValue and any resolver payload, and reports a datasource with children but empty fields (read elsewhere, not editable). The drop check compares only rows under datasource.children with the datasource's own children; a query that reads another path is reported as not checked. Exit 1 on a drop, non-jsonValue rows 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.
  2. 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 media System folder. ser pull afterwards, or the next push overwrites them.
  3. 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 jsonValue and rendered through an SDK field component with no editable={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 measured ComponentQuery budget 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

  1. Before placing a new file, decide: is it a Sitecore rendering, or is it infrastructure?
    • Sitecore rendering (matches a componentName in 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 in componentMap.paths. Gen-map will ignore it.
  2. Run npm run sitecore-tools:generate-map after creating/moving files. Inspect .sitecore/component-map.ts — every entry should correspond to a real Sitecore rendering.
  3. 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. toPascalCase splits 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.
  4. For variant files, use the <ComponentName>.<VariantName>.tsx convention. Gen-map merges them into one map entry: ['ComponentName', { ...Default, ...Variant1, ...Variant2 }]. The runtime picks the right export by params.FieldNames.

Hard Rules

  • sitecore.cli.config.ts declares componentMap.paths — usually ['src/components'] with exclude: ['src/components/content-sdk/*']. Anything under a scanned path is a candidate Sitecore rendering. Anything under exclude (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 in src/ui/, src/site/, etc.
  • Don't hand-edit .sitecore/component-map.ts. It's regenerated on every npm run dev / npm run build. Edits are lost. Adjust source structure or sitecore.cli.config.ts instead.
  • Map key === rendering componentName exactly — 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/content 2.2.x the key is toPascalCase(filename), which splits on [-_], so Navigation_Custom.tsx registers as NavigationCustom, 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, moduleName still 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's componentName has one, the rendering must be renamed on the CM (Authoring GraphQL updateItem on the componentName field); renaming the folder alone cannot fix it. Rename the rendering item at your peril — its path and its <X> Parameters template are path/GUID-coupled, and page layouts reference the rendering by GUID, so changing only componentName is 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-probe skill) to find the exact componentName string before naming the folder.
  • Only the Sitecore-registered .tsx file (and its .<Variant>.tsx siblings) belong inside src/components/<Component>/. Every other file — types (*.types.ts), GraphQL queries (*.gql.ts), sub-components (e.g. a client-side NavBranch.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's search-experience/search-components/ placed under src/components/ registers every hook and helper as a rendering (content-sdk-search). Atoms (beta.atoms) live in src/atoms/, outside src/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.ts is seen as variant types) 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 like LevelFrom, LevelTo, Styles, EnabledPlaceholders) and become invisible in Pages even though the field exists in the template. Use namespaced names (NavDepth, NavMaxItems) or singular forms (Level worked, Levels did not in one verified case). When in doubt, scope-prefix.

Stop Conditions

  • Stop and ask if the componentName from 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 in sitecore.cli.config.ts.
  • Don't create a component with a componentName that 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-map and 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 componentName must 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 no MissingComponent placeholder appears on any route. That is the reconciliation, performed empirically. See content-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 renamed NavigationCustom.

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:

  1. *.types.ts and *.gql.ts got interpreted as variants of Navigation_Custom (because the basename pattern <Component>.<X>.<ext> matches the variant-file convention). Their non-React exports (NavItem type, NAV_LEVEL_1_QUERY string) got spread into the Navigation_Custom map entry, polluting its export surface — componentMap.get('Navigation_Custom').NAV_LEVEL_1_QUERY becomes a string. Setting params.FieldNames="types" in a rendering instance would attempt to "render" the types module as a React component.

  2. NavBranch.tsx and actions.ts got registered as standalone Sitecore renderings named NavBranch and actions. If an author ever named a real rendering NavBranch it would collide. Even without collision, the SDK now believes NavBranch is 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's Home --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 no revalidate, 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 exact componentName from a live response.
  • content-sdk-website-build-flow § "Gate the PR preview deployment" — the CI gate that catches a key/componentName mismatch empirically, which no local check can.

References

  • scripts/assert-map-keys.mjs — keys vs serialized componentName values, plus the installed key rule; dependency-free Node.
  • .sitecore/component-map.ts — generated output (do not hand-edit).
  • sitecore.cli.config.ts — componentMap.paths + exclude config.

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

InputRequiredUse
Component name + head-app pathyessrc/components/<Name>/, the component map
CM path (<cm>/authoring/items/)yesrendering item, templates, branch, Standard Values as YAML
The planner's blueprintnowhen 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 endpointfor the live legthe 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):

SevMeans
P0broken for every author or visitor now (component un-editable, renders nothing, base chain empty)
P1breaks a real author task or the next push (no way to add a row, datasource in the wrong tree, a push that strands items)
P2degraded or risky (raw .value on one field, missing editing escape on a guard, a waiver without a reason)
P3hygiene (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.

#AxisLegOwning skill
A1Authorability: every authored value arrives on fields and renders through an SDK field component; exceptions per field, each with a reasonstatic + human— (scripts/audit-component-authorability.mjs)
A2Editing safety: renders in Pages edit, preview and the design library; empty fields stay selectablestatic + humancontent-sdk-app-router-editing-safe-rendering
A3Registration and naming: component map key = componentName; only registered .tsx under src/components/<Name>/staticcontent-sdk-component-naming-traps
A4Variant vs sibling: one rendering with variants, or a deliberate sibling; variant file namingstaticcontent-sdk-variants-vs-siblings
A5Data strategy: plain fields vs resolver vs ComponentQuery; no fetch replacing fields; Edge depth budgetstaticcontent-sdk-resolver-patterns
A6Content 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 mutatedstatic + livecontent-sdk-create-component
A7List wiring (list components only): the four legsstatic + live + humancontent-sdk-list-component
A8Template integrity: every project template's base chain resolves in the live enginelive only— (scripts/check-template-base-chain.mjs)
A9Serialization completeness: rendering, templates, branch, placeholder settings and Standard Values all covered; a template is serialized wherever its items arestaticsitecoreai-serialization
A10Comment economy: a comment says WHY in a line or two; walls are a smellstatic— (scripts/audit-comment-density.mjs)
A11Cross-cutting, where relevant: dictionary keys with a literal default, personalization scope, consent gating, cache tagsstaticper 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.mjs refuses 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:

ScriptFileWhere
authorability.authorability-ignore.jsonhead-app root; components and per-field fields ("<Component>.<Field>")
schema.schema-audit-ignore.jsonCM root; loose datasources carry their own reason
comment density.comment-density-ignore.jsonthe 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 template parser. 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-troubleshooting territory, 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>/:

  1. Datasource template (…/<Site>/<Name>) — the field set. Datasource templates and list element (child/row) templates sit at the root of the site folder.
  2. Folder template (…/<Site>/Folders/<Name> Folder) — holds datasource items; its __Standard Values.__Masters is 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 a Folders/ subfolder.
  3. Parameters template (…/<Site>/Rendering Parameters/<Name> Parameters) — rendering params. All parameters templates live in a Rendering Parameters/ subfolder.
  4. Rendering definition (/sitecore/layout/Renderings/Project/<Brand>/<Site>/<Name>, template Json Rendering).

✅ Content SDK: create the parameters template, LINK it, and FORCE-publish it — works IFF three conditions hold. Clone the <Name> Parameters template into Rendering Parameters/ and set the rendering's Parameters Template field = 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 serialize IStyling/Grid Parameters/IComponentVariant/ICacheable); (b) the rendering's Datasource Template is 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's layout query 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 copyItem of the template (extend/reorder fields). Recommended default; decouples from the source.
  • Inherit — create a new template whose __Base template points 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 kindClone source (JSS Experience Accelerator)__Base template (exact)
Standard datasourcePromoStandard template + _PerSiteStandardValues
Standard datasource — Rendering ParametersPromo ParametersBase Rendering Parameters + IDynamicPlaceholder + _PerSiteStandardValues + IRenderingId
List / collection container (Link List / IGQL children)Link ListStandard template + _PublishingGroupingTemplate + _HorizonDatasourceGrouping + _PerSiteStandardValues
List / collection element (child / row)Link (element)Standard template + _PerSiteStandardValues
List / collection — Rendering ParametersLinkList ParametersBase 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 &amp;, 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 typeSource
Rich Textquery:$xaRichTextProfile
Imagequery:$siteMedia
General Linkquery:$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 intentField typeSource
Boolean flag (e.g. sort Ascending — unchecked = descending)Checkbox(none)
Free text / numeric tokenSingle-Line Text(none)
Enumerated choice (sort order as a dropdown, colors, sizes)Droplink / Droplista 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…):

  1. Under the site's Rendering Parameters/ folder, create a Content folder, and inside it one folder per list — e.g. Rendering Parameters/Content/Colors, …/Sizes, …/Alignments.
  2. Create one item per choice inside that list folder, from a small Rendering Parameter Entry template that carries a Value field (e.g. Left → Value left, Center → center; or Ascending → asc).
  3. 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 Type is 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:

  1. the rendering (also de-register it from Available Renderings; this drops its Datasource Template Internal Link),
  2. every item based on the datasource template — its own __Standard Values, any authored datasources, and the Design Library Mock-<ComponentName> datasource (see below). The reliable way to find them all is an Authoring search on _template = the template id (32-hex, no braces/dashes) and delete each hit,
  3. the folder template, then the datasource template (sections/fields cascade),
  4. 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 — deleteItem keeps returning "used by at least one item" with no obvious culprit. Search _template to 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), a Template section, and Template field items (with Type + Source set via fields). All verified on the tenant.
  • update_fields_on_item(itemId, fields) is generic — it writes ANY field on ANY item: the rendering's componentName / Datasource Template / Datasource Location / Parameters Template, and the Available Renderings group's Renderings field → the rendering became placeable in the Pages picker (confirmed via get_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, billboard all render blank). The reliable, tenant-confirmed set is SXA/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 __Icon off OOTB renderings under /sitecore/layout/Renderings/Feature/Experience Accelerator/*, then map to those (or a confirmed Office/ name). Renderings under Feature/Experience Accelerator/ may prefer the SXA_MDI set.

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 __Icon on 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 fields will 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-debug route uses client.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) inside draftMode() instead of getPage. Add a ?mode=preview flag to the route if needed. Preview bypasses Edge.
  • Always wrap unknown components in ResolverProbe before 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-debug before production deploy. It leaks the layout payload (incl. internal item IDs). Gate by process.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 fields is 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.placeholders populated.
  • The InstrumentedFrame caption should match the layout response's componentName / dataSource exactly — if it doesn't, the wrong component is registered for that name.
  • A 500 from the route with Edge fetch failed usually means Edge context ID is wrong in .env.local; check SITECORE_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 Pagescomponent 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

QuestionOwner
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

ShapeUse whenWatch
Plain datasource fieldsone item, flat fieldsthe default; cheapest
SXA content resolver (e.g. datasource children)container + childrenchildren come back in item-name order unless __Sortorder is set
Integrated GraphQL (ComponentQuery)nested or cross-item data, list rowsit 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 branchesan 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 fields and renders through an SDK field component (Text, RichText, Image, Link).
  • Empty fields stay selectable while editing: guard with (isEditing || hasValue), never unmount on empty; set renderChildrenWhenEmpty on a Link that wraps children (its default is false).
  • 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 equal componentName).

6. Cross-cutting impact

Answer each with "none" or a named consequence. Silence is not "none".

ConcernQuestionOwner
i18nWhich fields are versioned, which Shared? New dictionary keys? Per-language routes?sitecoreai-localization, content-sdk-app-router-dictionary-and-i18n
Personalization / A-BWill marketers vary it? Then it must be a component with a datasource (variants swap datasources or hide components).sitecoreai-personalization, content-sdk-personalization
SearchIndexed? Which fields searchable / facetable? Reference fields are not indexed.sitecoreai-search-sources, content-sdk-search
Analytics + consentNew events? Gated by consent category?content-sdk-analytics-events, content-sdk-tracking-consent
Caching / freshnessWhich revalidation tags must a publish hit? Does the Edge webhook cover it?content-sdk-app-router-cache-components-and-osr
SEONew routes in the sitemap? Metadata fields? robots impact?content-sdk-app-router-sitemap-robots
MultisiteReused on another site? Datasource Location site-relative? Per-site <X> Folder needed?content-sdk-app-router-multisite-management
URLsDoes 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 with fields?. 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 stops undefined being 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 and null when 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) see content-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. Pass undefined so the attribute is omitted, or let <Link> render nothing for an empty field. Assert getAttribute('href') is null on 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>. withFieldMetadata wraps the whole <a> in the field chrome, whatever its children, so the field stays inline-editable, and an empty link still renders nothing unless renderChildrenWhenEmpty is set. showLinkTextWithChildrenPresent does 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 fields comes from is router-specific and out of scope here: App Router resolves it from getPage (and may pass it as serializable props from a Server Component to a Client Component); Pages Router resolves it via getComponentData from the [[...path]].tsx catch-all. For that wiring use content-sdk-app-router-component-data-strategy or content-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 __Icon standard 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:

ControlExpectedCatches
office/16x16/__control_not_real__.png404 + text/htmlAn auth redirect being read as success — an unauthenticated GET returns 302→200 for every path
office/16x16/window.png200 + image/pngAn 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.pngoffice/16x16/document_text.png
~/-/icon/office/16x16/navigate_right.pngoffice/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 existsitems hit (one brand)
office/16x16/document.pngoffice/16x16/document_text.png23
office/16x16/navigate.pngoffice/16x16/navigate_right.png16
office/16x16/flag.pngoffice/16x16/bookmark.png (or megaphone.png for campaigns)9
office/16x16/find.pngoffice/16x16/find_text.png8
office/16x16/image.pngoffice/16x16/photo_landscape.png7
office/16x16/settings.pngoffice/16x16/gearwheel.png2
office/16x16/database.pngoffice/16x16/server.png2
office/16x16/table_list.pngoffice/16x16/table.png / text_align_left.png3
office/16x16/document_check.pngoffice/16x16/document_selection.png / clipboard.png3
office/16x16/weather_sunny.pngoffice/16x16/sun.png2
office/16x16/palette.pngoffice/16x16/photo_landscape.png7
office/16x16/color_swatch.pngoffice/16x16/photo_landscape.png2

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 familyIcon path
PromoSXA_MDI/16x16/Promo.png
NavigationSXA_MDI/16x16/Navigation.png
Rich TextSXA_MDI/16x16/RichText.png
ImageSXA_MDI/16x16/Image.png
CarouselSXA_MDI/16x16/Carousel.png
Page ContentSXA_MDI/16x16/PageContent.png
ContainerSXA_MDI/16x16/Container.png
Search BoxSXA_MDI/16x16/SearchBox.png
Search ResultsSXA_MDI/16x16/SearchResults.png
Page ListSXA_MDI/16x16/PageList.png
TitleSXA_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 nameTokensMatched categoryChosen icon
DesignManifestodesign, manifestoContent (design+manifest)office/16x16/document_text.png
ContactDetailItemcontact, detail, itemPeople/Contact (contact wins)office/16x16/telephone.png
ContactDetailsFoldercontact, details, folderFolder override (ends in Folder)office/16x16/folder.png
ContactFormcontact, formForms (form wins over contact)office/16x16/checkbox_group.png
DestinationCarddestination, cardMap/Location (destination wins)office/16x16/map.png
DestinationsGridFolderdestinations, grid, folderFolder overrideoffice/16x16/folder.png
ExperienceItemexperience, itemNavigation (experience → journey)office/16x16/navigate_right.png
ExperienceShowcaseexperience, showcaseHero/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

PitfallWhat happensFix
Writing the semantic NAME as the pathThe 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 filenamesCopy the middle column of § 3/§ 8 verbatim. Never compose a path from the component's vocabulary. Blocklist: § 3a
Trusting the catalog without probingupdateItem 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 itProbe 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 controlAn unauthenticated GET returns 302 for every path, real or not, so "not 404" reads as success and every icon looks aliveSend 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 controlAn 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 positivesAssert 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 tokenIt expires in ~24 h, so the sweep silently degrades into the false-positive case above overnightMint a client-credentials token instead (clientFor('<org>')), which also asserts the tenant claim
Assuming a folder or size substitutionOffice/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 tooNo inference rule exists. Probe each candidate
Wrong case in icon pathIcon not found → blank/broken icon in CMUse exact casing from § 9 catalog
Including ~/-/icon/ prefixField stores the full URL, resolves to double-pathStrip prefix; use office/16x16/person.png only
Updating a read-only or locked itemGraphQL returns errorUnlock item first via Content Editor or unlockItem mutation
Setting __Icon on a rendering item inside a folder templateWorks but the folder's icon also changesIf you only want the rendering icon, target the rendering item's GUID specifically
Empty string valueFalls 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 renderingMay not resolve visuallyOnly 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 undefined in 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

  1. Placeholder keys. Edge delivers container-{*}, column-N-{*}, row-N-{*} and puts the instance id in params.DynamicPlaceholderId. Name the child placeholder column-${n}-${DynamicPlaceholderId}: the SDK matches it against ^column-N-\d+$. The literal column-N-{*} also works. A fixed name such as column-1 finds nothing, and nothing errors.
  2. 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.
  3. 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.
  4. params.styles is computed by the SDK from GridParameters + Styles, and is absent when both are empty. Interpolating it prints undefined.

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 via ColumnWidthN. 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-6 at Mobile). The narrowest column stacks first, never below ~240 px. No orphans. Standard layouts:
DesktopTabletMobileClasses
121212col-12
6/66/612col-12 col-md-6
8/4 · 4/88/412col-12 col-md-8 / col-12 col-md-4
9/3 · 3/91212col-12 col-lg-9 / col-12 col-lg-3
4/4/41212col-12 col-lg-4
3/3/3/36/612col-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 (template assets/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

  1. Copy the helper: assets/layout-params.ts → src/lib/layout/layout-params.ts. Never place it under src/components/, where generate-map registers every file as a rendering (content-sdk-component-naming-traps).
  2. Copy the components from assets/components/: Container.tsx, ColumnSplitter.tsx, RowSplitter.tsx, each into src/components/<Name>/<Name>.tsx. The file name must equal the componentName. They are upstream's markup with the defects fixed (no undefined class, EnabledPlaceholders order with a fallback, a placeholder name that survives a non-numeric id). Keep PartialDesignDynamicPlaceholder from the scaffold.
  3. Add grid CSS: @import assets/bootstrap5-grid.css at the top of src/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-N rules 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).
  4. Make ordinary components honour grid params: add a params prop where a component takes only fields, and put className={cx('component <own-classes>', styleClasses(params))} on its root element.
  5. Nested placeholders always use AppPlaceholder with the server map (import componentMap from '.sitecore/component-map'). The bare Placeholder resolves the client map in App Router, and every child renders "unknown component".
  6. npm run sitecore-tools:generate-map; check the keys Container, ColumnSplitter and RowSplitter are present, and update any component-map key snapshot test the app keeps.
  7. 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.
  8. 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.
  9. Run node scripts/check-layout-wiring.mjs --app <head-app>, then Verification below.

Procedure: custom slot component

Follow references/custom-layout-component.md:

  1. Decide the slot prefix, the slot count and the presets.
  2. Create the items: a params template on BaseRenderingParameters + IDynamicPlaceholder, one Placeholder Settings item per slot (<prefix>-N-{*}), and a Json Rendering with Placeholders and OtherProperties = IsRenderingsWithDynamicPlaceholders=true. Then Available Renderings, and Style items for the presets. Item mechanics: content-sdk-create-component.
  3. Copy assets/components/LayoutGrid.tsx + layout-grid.css and adapt PREFIX and PRESETS.
  4. 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

SymptomCauseFix
"Container — Content SDK component is missing React implementation"The scaffold ships no structure componentsStep 2
Columns stack like rows; container invisible; dropping a splitter "deletes" the pageNo CSS for the runtime grid classes, or it was purgedStep 3
Children never render inside a column; console "Placeholder 'column-1' was not found"A fixed placeholder nameslotName()
Children render as "Placeholder X contains unknown component"Bare Placeholder, which uses the client mapAppPlaceholder + server map
class="row component column-splitter undefined"Raw ${params.styles}styleClasses(params)
Eight columns render, six of them emptySlots taken from rendering.placeholdersenabledSlots(params)
Author sets a width in Pages, nothing changesThe component ignores its paramsStep 4
The Column Splitter panel has no width controlWidths live on each columnSelect the column, then Design → Layout → Size
A fresh two-column splitter stays side by side on phonesPages gives a new column col-6 at MobileSet 12 at Mobile, override at a larger breakpoint
An app's own .row band shifts or gets padded after adding the gridAn unscoped grid .row ruleThe scoped bootstrap5-grid.css (0.2.0+)
Splitter rows turn into the app's own 100vw bandThe app's unlayered .row rule winsScope the app rule (app-css-collision)
The page is 12 px wider than the viewportRow negative margin with no padded parentThe grid's Container padding (0.2.0+)
A component overflows or breaks words in a narrow columnIt sizes itself by the viewportRe-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 secretgrid-and-css.md § 4
A layout written through GraphQL renders nothingNot Pages' delta form, or updateItem without version: 1standard-structure.md § 4a
Grid change not visible locallyTurbopack does not hot-reload globals.cssStop the dev server, rm -rf .next, restart
A Bootstrap 3 col-xs-* from migrated contentThe source grid survived migrationThe static grid aliases col-xs-*
Content vanishes after switching a presetIt sits in a slot the new preset does not renderSwitch 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, unguarded styles and slots taken from placeholders (FAIL or WARN); components ignoring their params (WARN). Exit 1 on FAIL. --self-test runs 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-file at a PREVIEW context for unpublished pages; in Git Bash prefix MSYS_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 at md and 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?

AnswerShape
No — a fixed set of the datasource's own fieldsSingle component. One datasource template. Done.
Yes — repeating rows: nav links, cards, stats, entries, panels, tabsList 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:

LegWhat it buysmeasured
0. _HorizonDatasourceGrouping base templatethe 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 SVinsert options — which template a new child uses✅ correct on all four
2. Datasource Template = a BRANCHa new datasource ships with a row already in it❌ bare template
3. children-aware deliverythe 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.

RankMechanismNote
1Integrated GraphQL (ComponentQuery) with every field as jsonValueExpresses 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).
2Component-level fetchA 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.
avoidChildren content resolverDelivers 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):

  • children nested two levels deep inside a ComponentQuery breaks resolution. The rendering arrives with isContentResolved: false and no error. Keep the query to one level of children, and fetch deeper rows server-side with client.getData.
  • A row past children(first: N) is silently dropped. first must be strictly greater than the authored row count, or the row an author adds in Pages never reaches the page. Size first to the real row count plus headroom, not a blanket 50, because first:50 alone can exceed Edge's complexity budget. Record each list's maximum authorable row count next to its query.

Build order

  1. Create the element template (row fields). Icon it.
  2. Create the container template (list-level fields). Icon it. Add __Standard Values.
  3. Set the container SV's __Masters to the element template id. ← the step that is easy to skip and defines the outcome
  4. Create the branch under /sitecore/templates/Branches/…, $name on the container template, carrying __Masters and one default element.
  5. Point the rendering's Datasource Template at the branch.
  6. Wire delivery: a ComponentQuery with jsonValue fields, the resolver cleared (ranking in leg 4). 6a. Set __Sortorder on 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).
  7. 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, the copyItem recipe
  • content-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 shapes
  • content-sdk-icon-chooser — the __Icon step 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.

QuestionShape
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 id must 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 fields and 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: rootPath resolves 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 a ComponentQuery that 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 PersonalizeProxy and sitecore.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):

  1. Returns early when disabled (enabled:false, no Edge config, a path containing ., or skip() returns true), on a redirect, on preview, or on sc_bot.
  2. Reads the route's personalization { variantIds } from Edge (edgeTimeout, 10 s in-process cache).
  3. Returns on no personalization or on a prefetch (Cache-Control: no-store, x-proxy-cache: no-cache).
  4. Calls initContentSdk with the server context id. This sets sc_cid and sc_cid_personalize with both cookie flags hard-coded on. On a personalized route with marketing consent this is the guest mint: Set-Cookie on the document, and the browser's create.json disappears (measured 2026-10-07; tests: references/verification.md § Testing notes).
  5. Sends one personalize() per friendlyId in parallel (cdpTimeout), with UTM, referrer, User-Agent and the optional geo.
  6. Drops any returned id that is not in the Edge list, then rewrites to /<path>/_variantId_<page>[/_variantId_<comp>_<var>].
  7. 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
},
  • enabled defaults to NODE_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]. Set enabled:false on sites without personalization: it removes the lookup and the noise.
  • Timeouts read PERSONALIZE_MIDDLEWARE_EDGE_TIMEOUT and PERSONALIZE_MIDDLEWARE_CDP_TIMEOUT (400 ms each). The template's sitecore.config.ts.example reads PERSONALIZE_PROXY_EDGE_TIMEOUT for 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's PAGES_PERSONALIZE_SCOPE gives 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

ThingFormExample shape
Edge page variant idno _<v>
Edge component variant id<componentId>_<variantId>; <componentId>_default is the control<c>_<v>
Page friendlyIdembedded_[scope_]<pageIdNoDashes>_<lang>CdpHelper.getPageFriendlyId(pageId, lang, scope)
Component friendlyIdcomponent_[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, personalizeLayout renders a hidden variant as the hidden-rendering placeholder instead of removing it, so the author can still select it.
  • PersonalizeProxy and BotTrackingProxy skip preview; Bootstrap does not init in draftMode. A self-invoked browser personalize() therefore throws IE-002 in editing: branch on page.mode.isNormal.
  • next dev disables the proxy (enabled default) 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 (from sc_cid) is sent only when you pass no email and no identifier. 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 variantId against the candidates you sent, as the proxy does.

Full wire body, error table and longer code: references/self-invocation.md.

RuntimeHowVerdict
Client componentAdd personalizeBrowserPlugin to Bootstrap's plugin array; call after initOK. Never call initContentSdk a second time: it replaces Bootstrap's plugins
Route HandlerinitContentSdk + analyticsProxyAdapter / personalizeProxyAdapter with a carrier responseWorks, but not concurrency-safe
Server ComponentHand-written adapters over cookies() / headers(); both cookie flags falsePossible; same singleton risk; feed UTM from searchParams
ProxySubclass PersonalizeProxy; override the protected getExperienceParams / getPersonalizeExecutionsBest for extra params or extra friendlyIds: reuses init, rewrite and fail-open
Any server codePlain fetch of the wire contractRecommended 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'); normalizePersonalizedRewrite gives 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 explicit personalize wins 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 from page.tsx.
  • Other proxies can read SuccessfulPersonalizeProxyExecution from proxiesContext, but only if you pass a Map into exec(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/personalize forwards 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 run personalizeLayout). Measured (P7): Edge carries the copied datasource's full fields under experiences[<v>] for a datasource-only COPY, and the decision ignores URL, siteId and body language (friendlyId + params decide). So the decision side works from any route. Whether Pages accepts a hidden decision page is not run.
  • webPersonalization is not an option on embedded tenants. On both tenants probed, /v1/personalize/cdn-url pointed at a cloud-version.min.js that returns 403, so the plugin injects a script that does nothing. Its defer and language options are ignored, and browser init exposes window.scContentSDK.personalize to 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

BehaviourStatus
Personalized responses get x-proxy-cache: no-cache; prefetch skips the decision with Cache-Control: no-storecode-verified
generateStaticParams emits base paths only, so variant paths render on demandcode-verified
'use cache' keyed on {site, locale, path} gives one entry per variant path; cache tags strip variant segments, so one revalidate covers all variantsinference 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 therefrom 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.

LayerPassControl
3 Edgepersonalization.variantIds non-empty; the rendering has experiences[<v>]A plain page returns [] (never null) and has no experiences key
4 DecisionDirect 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 RenderProduction build, LIVE Edge, non-headless UA, consent set, DEBUG=content-sdk:personalize shows the _variantId_ rewriteWithout the condition: the default
6 BeaconVIEW 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.enabled explicitly; false on a site without personalization.
  • skip reads consent. Never let the proxy run, and set cookies, for a visitor without consent.
  • Keep BotTrackingProxy before PersonalizeProxy.
  • Pass a timeout to every SDK personalize() 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/about probably 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

  1. Choose a topic-scoped folder, outside any real project, for example playground-navigation/ or playground-redirects/. Keep it out of real project folders so their tooling and CI never pick it up.
  2. Scaffold the SCS solution side with dotnet sitecore plugin add Sitecore.DevEx.Extensibility.XMCloud@<v>, then dotnet sitecore init, then declare modules in authoring/items/<module>.module.json. Connect to a Cloud environment per the sitecoreai-cli-cloud-workflow skill.
  3. Scaffold the head app side inside sites/<topic>/ with npx --yes create-content-sdk-app@latest --yes --template nextjs-app-router --destination sites/<topic> (per the setup-content-sdk skill, which also covers the Pages Router template). Treat this as a regular Content SDK head app — src/, .sitecore/, etc.
  4. Wire xmcloud.build.json at the playground root to point renderingHosts.<host>.path at ./sites/<topic>.
  5. Capture an Edge snapshot at the start. Create edge-snapshot/ and save (capture-edge.mjs in the sitecoreai-edge-graphql-capture skill does this; Edge rejects a full introspection query, so it introspects per type):
    • sites.json, routes.json — sites and routes query responses
    • type-<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
  6. 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.
  7. Install the content-sdk-debug-layout-probe toolkit 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 — same AGENTS.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 updates authoring/items/items/... deterministically.
  • npm run dev in sites/<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 for sites/<topic>/.
  • sitecoreai-cli-cloud-workflow — for the authoring/ side.
  • sitecoreai-edge-graphql-capture — for edge-snapshot/.
  • content-sdk-debug-layout-probe — install this in sites/<topic>/ on day one.
  • content-sdk-resolver-patterns — the catalog of patterns a playground exists to learn.

References

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 typeShapeTrap
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:

  1. Droplink / Droptree fields (All-Fields pattern, single)
  2. Treelist / Multilist / Checklist field values (All-Fields pattern, array)
  3. 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 typeEmpty-state shapeDefensive 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 inside rendered.sitecore.{context,route} is untyped JSON. There is no schema-level type safety for fields. 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 ResolverProbe dummy first (see content-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-resolver items[i].fields, render manually using item.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).
  • dataSource is 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 dataSource is 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-probe to capture).
  • For Children-resolver renderings, verify the items[i].fields shape against your expected per-item field set. The wrapper is always {items:[...]}; only the inner fields varies.
  • The InstrumentedFrame tone should match the identified pattern (accent / ok / warn / ink) — that's a visual sanity check.
  • If fields is 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

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 wantUseNot
Site/product search with marketer-tuned boost, pin, facetsthis skill + sitecoreai-search-sourcesEdge GraphQL search(where:) (filters an item's own fields only)
Exact structural queries (children of X, by template) inside a data fetchEdge GraphQL / ComponentQuery (sitecoreai-graphql-schemas)integrated search (index lags until a manual reindex)
Recommendations, widgets, rfk_id, customer key, discover.sitecorecloud.iostandalone Sitecore Search (CEC)this skill
CM item lookup during authoring automationAuthoring GraphQL search(query:)either search product

Preflight (all must pass before UI code)

  1. 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 of sitecoreai-search-sources (needs a credential with the search-config scope). No source, no search: an unknown id answers 404 no search index found for config <id> [confirmed].
  2. SDK floor: npm ls @sitecore-content-sdk/search. Search rides on nextjs (nextjs → react → search). 0.4 (nextjs 2.3) adds locale + facet; 0.5 (nextjs 2.4) adds suggest() + MLT. Table: references/version-matrix.md.
  3. NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_ID is set (api.edge.clientContextId). Without it useSearchService() returns null and every hook stays status: 'idle' forever with zero requests and no error [confirmed: P8, 0 requests in 5 s]. A missing searchIndexId instead gives status: 'error'.
  4. 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 404 No sitecore context), then a fake-index control (must be 404 no search index found), then your query.

Choose the surface

SituationUse
Interactive search box, paginationuseSearch / useInfiniteSearch from @sitecore-content-sdk/nextjs/search, in a 'use client' component, inside a component-local <Suspense>
TypeaheaduseSuggest (no built-in debounce: debounce the input yourself)
SEO-visible results, a "related content" block, a route handlernew SearchService({ contextId }) on the server
Related itemsMLT: 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. fetchOptions is spread into the global fetch, 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; under dynamic = '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 sessionId is '' (no analytics init): search works but is not tied to a CDP session.
  • Errors throw Error('HTTP 404 Not Found') with e.response.status and e.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 default SearchDocument value type is not a ReactNode, 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 sort and facet object [confirmed: P8]. They are useCallback dependencies compared by reference. An inline facet={{ all: true }} produced 6,568 requests in 5 s, 6,600 renders, status stuck at loading (each render aborts the previous request). The useMemo version sent exactly 1. check-search-wiring.mjs fails the inline form.
  • limit max 500 (RangeError); limit: 0 passes validation [source]. An empty keyphrase returns the whole index.
  • page is 1-based; useInfiniteSearch.hasNextPage = results.length < total.
  • Each new request aborts the previous; aborted errors are suppressed.
  • Hooks do not pass locale for you. Pass the route locale explicitly on a multi-language site; the accepted format (en vs en-US) [probe-gated: P4].
  • Facet name is the facet's display name from the source config, not the raw field name (SDK JSDoc). Operators eq|gt|lt|ge|le; string/boolean fields eq only; an array value means OR. Server behaviour [probe-gated: P4]. Discover names with search-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):

  1. Encode ?q=. useRouter.tsx builds `?q=${value}`; &, #, + corrupt the URL. Use encodeURIComponent(value).
  2. Compute nullResults. useEvent.tsx hard-codes nullResults: false, so the dashboard's Null searches KPI can never fire. Pass total === 0.
  3. Gate the event on consent. The starter calls event() directly. Route it through trackEvent() from content-sdk-tracking-consent (analytics category). Consent denied: no event, and sessionId is '', but search itself keeps working.
  4. Keep <Suspense> local. useSearchParams needs a boundary for next build; the starter wraps all of Providers, which makes the whole tree client-rendered. Wrap only the search component.
  5. Type SearchDocument from your source's real fields (the starter hard-codes SYNC product fields). Capture a response with probe-search.mjs --out first.
  6. Fail loudly on bad config. useSearchField falls back silently on an empty value, console.warns on invalid JSON, and casts valid JSON without validation (missing searchIndex → undefined). In editing, render an author-visible notice instead.
  7. Also: the starter omits componentInstanceId from the event (A/B/n attribution); its md:${baseClass} grid class is built at runtime and is invisible to Tailwind's scanner, so safelist the three md: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.mjs against 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, inline sort/facet literal or one built in the render body without useMemo, unencoded ?q=, nullResults: false literal, type: 'search' event with no consent guard. WARN: SearchService without a direct @sitecore-content-sdk/search dependency, no client context id in env files, hook call without locale, search event without componentInstanceId, <Suspense> wrapping Providers, runtime-built Tailwind classes.
  • Both: --self-test runs fixtures plus a mutation sweep that disables each guard in turn and fails if no case notices.

Traps index

  1. 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".
  2. Unknown index with a good context → 404 {"errors":[{"message":"no search index found for config <id>","code":404}]}.
  3. Missing client context id → hooks idle forever, silently.
  4. Inline sort/facet → request storm.
  5. Hook in a Server Component → prerender useState is not a function.
  6. SearchService needs a direct @sitecore-content-sdk/search dependency.
  7. Empty keyphrase returns everything; limit: 0 is accepted.
  8. Search does not run in Page Builder or Preview.
  9. Starter: unencoded ?q=, nullResults: false, ungated event(), Suspense around Providers, no componentInstanceId, runtime Tailwind class.
  10. Do not confuse CM Solr search(...), Edge search(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.ts with defineConfig; read all secrets and env-specific values from process.env.*. Add or change vars in .env.example (or .env.remote.example / .env.container.example) with placeholders; never commit .env or .env.local.

Hard Rules

  • Use sitecore.config.ts with defineConfig from 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 .env or .env.local; they are gitignored. Example files are the source of truth for which vars exist.
  • defaultLanguage resolves 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 the i18n block (locales, defaultLocale) in next.config.js with per-request context.locale. For that, use content-sdk-app-router-dictionary-and-i18n or content-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 / keyEffect
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_SCOPEpersonalize.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_TIMEOUTpersonalize.edgeTimeout / cdpTimeout in ms, default 400 each
NEXT_PUBLIC_SITECORE_EDGE_CONTEXT_IDapi.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_HOSTNAMEapi.edge.edgeUrl; empty = https://edge-platform.sitecorecloud.io
SITECORE_ENABLE_BOT_TRACKING=trueTurns BotTrackingProxy on in development / localhost, where it is off by default
  • Template trap: the scaffold's sitecore.config.ts.example sets edgeTimeout and cdpTimeout from PERSONALIZE_PROXY_EDGE_TIMEOUT, a name define-config does not read. If you copy it, one var drives both timeouts, and when it is unset parseInt yields NaN, which resolveConfig silently replaces with the PERSONALIZE_MIDDLEWARE_* / 400 default. No error either way. Use the PERSONALIZE_MIDDLEWARE_* names, or omit the keys.
  • defineConfig has 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, the PersonalizeProxy in src/proxy.ts, or any event() / 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

CategoryWhat it switchesLever
necessary (always on)site_consent (this skill), sc_site (multisite routing), sc_bot (bot UAs only)none: these never carry a visitor identifier
functionalapp-owned preferences: theme in localStorage, a locale preference the app persistshasConsentClient('functional') around each write in store code (theme stores are plain functions, not hooks); useAllows('functional') in a component
analyticsBootstrap initContentSdk (analytics + events plugins → create.json, sc_cid), CdpPageView VIEWs, custom events, <Form> eventsgate 1 (Bootstrap), gate 2 (CdpPageView + trackEvent)
marketingPersonalizeProxy 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 }
  • v is the code-level CONSENT_SCHEMA. Bump it when the category set changes. An old v reads as no consent everywhere, the proxy included.
  • pv is the authored PolicyVersion the visitor answered. A mismatch re-prompts on the client; the previous choices hold until the visitor answers.
  • t is the decision time, kept for the audit trail.
  • Attributes: Path=/; SameSite=Lax; Secure; Domain=<hostname minus www> (the same rule Bootstrap uses for sc_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. Gating CdpPageView alone still runs create.json and sets sc_cid. A shipped "scope gate" did exactly that: a guest and a 730-day cookie per visitor, with zero views.
  • Add analytics (from useAllows) 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 .catch swallowed it, and no VIEW was sent (state D, measured). The dep is load-bearing for state B too: during hydration useSyncExternalStore returns the server snapshot ('', no consent), so the first effect pass always skips and the init happens on the post-hydration re-render. A not initialized: no analytics consent debug line on every cold load, consented or not, is expected.
  • Ordering holds by tree position. <Bootstrap/> is the first sibling in src/app/[site]/layout.tsx, and initContentSdk assigns 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() returns NODE_ENV === 'development' || !analytics, and analytics is in the deps, so a grant sends the current page's VIEW.
  • All app code sends custom events through trackEvent (analytics) and identity through trackIdentity (marketing, because IDENTITY carries PII). Never import event() / 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 and sessionId: ''; the search itself keeps working.
  • <Form> (SDK) subscribes to submit and calls form() 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-day site_consent.
  • On every save without analytics (not only on a granted → denied transition), delete sc_cid + sc_cid_personalize (and the legacy sc_<contextId>[_personalize]) for host-only, apex, www.<apex> and the full host. Both cookies are JS-set or non-HttpOnly. On www, Bootstrap and a proxy-style writer produced two sc_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, while sc_cid lives 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, keep sc_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) into Consent Banner, Folders/Consent Banner Folder, Rendering Parameters/ConsentBanner Parameters and the rendering ConsentBanner, plus a Data/Consent Banner container holding the one shared item. Names, field sources, the __Standard Values the 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" with aria-modal="false" on first visit (no trap), labelled by Title and described by Body. Native checkboxes in a fieldset. On reopen, focus goes to the heading, Escape closes, and focus returns to the trigger.
  • Versioning: bump PolicyVersion to re-prompt. Bump CONSENT_SCHEMA (code) when categories change.
  • Hydration: the dialog renders only after hydration (a useSyncExternalStore hydrated 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 fields absent. The asset is wrapped in the SDK's withDatasourceCheck, so editing shows a visible "choose its datasource" placeholder instead of nothing, and normal mode renders nothing. Never ship a bare if (!fields) return null.
  • Styling: the asset ships no CSS. Unstyled, the dialog is plain flow content, not a banner. The app styles .consent-banner with its own tokens.
  • Preview: it renders nothing. Bootstrap already skips init when draftMode() is on, and CdpPageView skips 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:

StatePass
B consent before loadcreate.json 201 + VIEW 201, then a VIEW 201 per soft navigation
A no consent0 /v1/events* and /v1/personalize* calls. No sc_cid / sc_cid_personalize. Banner visible
D grant mid-sessioncreate.json 201 + VIEW 201 for the current page, with no new document request
C withdrawtracking cookies gone on every domain, then 0 beacons across soft navigations and a reload
C2 stale sc_cid, no readable consentReject 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 initContentSdk without 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 dev server, 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_cid differently.
  • 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]

ItemGate
Proxy-issued sc_cid / sc_cid_personalize on a personalized routeMEASURED (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 consentP16 (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 appa 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 Pagesan 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: the useSyncExternalStore store 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 of src/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)

  1. 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.
  2. 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.
  3. Read the raw payload before reading the component. If layout.sitecore.route or fields is wrong, no amount of JSX change helps (content-sdk-debug-layout-probe).
  4. 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.
  5. Assert the first HTTP status, unfollowed. curl -L behind SSO or a login shell follows to a sign-in page and reports 200. Use curl -sS -o /dev/null -w '%{http_code} %{redirect_url}'.
  6. 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.
  7. 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.
  8. Never print secrets. DEBUG=content-sdk:editing logs 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

SymptomStart at layerFirst instrument
Hydration error, wrong theme flash, dead click, console errorBrowser / clientDevTools console + network
404 / 500 locally, wrong site, wrong language, redirect loopHead-app server + proxynext dev stdout with DEBUG=content-sdk:*
Page 200 but a zone or component emptyLayout payload (Edge)content-sdk-debug-layout-probe, then Edge GraphQL
Works on preview, wrong or 404 on liveEdge preview vs livethe same query on both contexts, side by side
Content edited and published, live unchangedPublishing + cachepublishing job status, webhook lastRuns, ISR window
Pages: no chromes, "Preview content is not found", component not foundEditing host + Pagesediting-host RenderingHost log, /api/editing/config status
Build or deploy red, or green but never servingDeploy / builddeployment record + logs, Vercel build log
Item missing, template gone, publish failsCMCM Log / Publishing files via the Monitoring API
Live site not indexed, assets 404, protection wrongHosting / deliveryunfollowed 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:

LayerWhere the signal isWatch for
BrowserDevTools console + network; localStorage.debug = 'content-sdk:*' for client-side SDK logsfirst error, not the cascade; the RSC payload contains the not-found copy on every page
Head-app servernext 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 hostMonitoring API, RenderingHost.* files, listed only under the editing-host environment idraw stdout, no timestamps
CMMonitoring API, Log.* / Publishing.* per instance and daymatch by level; signatures in the log-signatures reference of sitecoreai-health-check
DeployDeploy deployment record + /api/deployments/v1/{id}every line is info: read calculatedStatus and *LastFailureMessage, not levels
PublishingPublishing API job status (sitecoreai-publishing)job done ≠ Edge updated: check the item on Edge
Edge → app cacheEdge Admin GET /webhooks/{id} → lastRunsa 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

ClaimOnly this proves itNever use
"It is published"live Edge context read of the item / routeAuthoring GraphQL, the preview context, the publish job status
"Master is correct"Authoring GraphQLEdge in any context
"A visitor sees it"unfollowed HTTP or a real browser on the live hostcurl -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 idthe local .env.local
"The editor can author it"Pages: select the field and change ita 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 / topicLoad
Pages editing, preview, Design Librarycontent-sdk-app-router-troubleshoot-editing, content-sdk-app-router-editing-safe-rendering
Empty or wrong fields, resolver shapecontent-sdk-debug-layout-probe, content-sdk-resolver-patterns
Component not found / MissingComponentcontent-sdk-component-naming-traps, content-sdk-app-router-component-registration
Route, 404, placeholderscontent-sdk-app-router-route-configuration
Proxy, site resolution, redirectscontent-sdk-app-router-multisite-management
Language, dictionarycontent-sdk-app-router-dictionary-and-i18n, sitecoreai-localization
Stale after publish, revalidationcontent-sdk-app-router-cache-components-and-osr, sitecoreai-edge-admin-webhooks
Publish jobssitecoreai-publishing
Edge query errors, depth, complexitysitecoreai-edge-graphql-capture, sitecoreai-graphql-schemas
Serialization, ser pull / pushsitecoreai-serialization, sitecoreai-cli-cloud-workflow
Robots, sitemapcontent-sdk-app-router-sitemap-robots
Variants not showncontent-sdk-personalization, sitecoreai-personalization
Tracking, consentcontent-sdk-tracking-consent, content-sdk-analytics-events
Search UI idle or emptycontent-sdk-search, sitecoreai-search-sources
Theme flash, hydrationcontent-sdk-app-router-theme-hydration-pattern
After an SDK upgradecontent-sdk-upgrade-assistant
Env vars, site configcontent-sdk-site-setup-and-env
Whole-environment healthsitecoreai-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-git case below.

How to perform

  1. Release notes — the primary source, and NOT CHANGELOG.md. The repo's CHANGELOG.md stops 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; the cli is the component-map generator). URL shape: https://github.com/Sitecore/content-sdk/releases/tag/<package>%40<version> (@ encoded); gh api repos/Sitecore/content-sdk/releases lists 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.
  2. 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-core alongside nextjs / 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.
  3. Measure the OOTB surface — before touching package.json:
    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
    
    It scaffolds both references (reused across runs; --fresh rescaffolds), auto-detects the router (--template overrides), 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).
  4. 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 paired next.config rewrite or .env*.example entry (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 } vs import { Metadata }, or spreading ...getPageMetadata() under the app's own alternates, 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.
  5. 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).
  6. Prove the upgrade landed — rerun against the pre-upgrade lockfile, which lives in git now that the working tree is on the new version:
    node scripts/upgrade-surface.mjs --app <head-app> --from-git HEAD~1 --quiet   # exit 0, or the list of what is still missing
    
    Test editing, preview and the Components Preview page on the editing host after the deploy.

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 npx cannot reach the registry the upgrade is blocked, not estimated.
  • CHANGELOG.md is 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.2 all pin ^2.3.0, 2.4.0 pins ^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 --from explicitly then. Read the version from package-lock.json, never the ^ range.
  • Search rides on nextjs: 2.3 adds facet + locale, 2.4 adds suggest + more-like-this. upgrade-surface.mjs does not diff the search API; read packages/search/CHANGELOG.md (content-sdk-search).
  • 3.0.0-beta.atoms is a sideways move, not an upgrade: since the 20261021204512 stamp it is stable 2.4.1 plus atoms (earlier stamps forked pre-2.3 dev and 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.ts chain (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.md are excluded from the surface by default (--include-docs re-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 --to to see the latest stable and the surface it implies, then ask.
  • Stop if a NEW ABSENT route or a CUSTOMIZED hunk 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

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

VariantSibling component
Sitecore rendering itemSame rendering, different FieldNames paramDifferent rendering item entirely
componentName in layout responseSameDifferent
Rendering Contents ResolverShared (set on the rendering)Each sibling can have its own
Datasource TemplateSharedEach sibling can have its own
Parameters TemplateSharedEach sibling can have its own
Datasource Location querySharedEach can have its own
ComponentQuery (Integrated GraphQL)SharedEach can have its own
Author swap cost in PagesOne dropdown clickRemove + add a different rendering
Headless Variant item required for author UIYes — one per variantN/A
Head-app file convention<Component>.<VariantName>.tsx, merged into one map entrySeparate 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 Resolver GUID → siblings (e.g., the 4-resolver 2×2 family in content-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 Location constraint → 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's export default — i.e., the main Promo_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 valuePathWhat 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:

  1. Case-sensitive. FieldNames value must match the export name exactly (Fancy ≠ fancy).
  2. 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 FieldNames to the alphabetically first variant, before the head app sees it (§ Authoring side).
  3. 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 .tsx files.
  • The item name (e.g. Fancy) becomes the FieldNames value 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 .tsx export, 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:

  • FieldNames in s:par is 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 Default Headless Variant item once any sibling variant exists, and reference its GUID. Without that item, an omitted FieldNames means "first child", not "Default". "Default" resolves only on a rendering with no variant items.
  • Every other parameter needs its own key=value token (FieldNames={GUID}&HeadlineStyle=eyebrow). A save can also rewrite s:par as 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.
  • FieldNames value === React export name, case-sensitive. No casing normalization, no fuzzy match.
  • Variant addition is two-step: create .tsx export 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 its export default wins as component.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 on component.Default being picked via path A — it's only picked via path B (as the second link after component.default).
  • For a clean sibling, create a separate folder with its own componentName matching the rendering item exactly (see content-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 .tsx without 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 .tsx export — 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.ts should have the variant's import alias added alongside the others, and they should all merge into the same componentName map entry.
  • Set FieldNames to the variant name in Pages → the head app should render the variant's component.
  • Set FieldNames to a deliberately wrong name → the head app should render <MissingComponent> and log a warning to console (proves the resolution flow is wired right).
  • Clear FieldNames entirely → the head app should render the default variant (the main file's export). On a rendering with Headless Variant items, assert that the resolved params.FieldNames is Default and 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 resolves FieldNames to an export).
  • DEFAULT_EXPORT_NAME constant: @sitecore-content-sdk/react/dist/cjs/components/sharedTypes/components.js = "Default".
  • Captured example: a Promo component with four variants (Default, Fancy, Full, Minimal) and the four matching Headless Variant items under the site's Presentation/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)
ArtifactsRenderings, parameters/datasource templates, Headless Variants, content items, site collection / site nodes, publish eventsComponents, queries, route handlers, theme, chrome, build output
Source of truthLive tenant (*.sitecorecloud.io); authoring solution mirrored via ser pullHead-app repo (editing host)
SyncAuthor live (to preview); dotnet sitecore ser pull into the CM authoring solution — never pushPort / 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.

ScenarioContent modelStatic reference app (optional)Provisioning shape
NEW siteDerived from design / static props / clickdummy; authored live during implementationBuilt before the head app if used; props chosen freelyFull cascade: project → CM env → editing host → collection → site; create CM baseline when the CM is new
EXISTING siteAlready exists — inventory first (templates, datasource field types, renderings, resolvers)If used, props bounded by inventoried field shapesCreate 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).

SituationApproach
Tenant provisioned + visual design / clickdummy approvedBuild 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 artifactProduce the separate static app, then port
Incremental addition to an already-built head appPer-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

  1. 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.
  2. Wait ~1–2 minutes (or poll until past Edge-resource creation) before deploying the editing host.
  3. 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.

ConstantValue
Default layout device ID{FE5D7FDF-89C0-4D99-9AA3-B5FBD009C9F3}
Default layout ID{96E5F4BA-A2CF-4A4C-A4E7-64DA88226362}
Header placeholderheadless-header
Footer placeholderheadless-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 Droplink override 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 in route.fields['<Field>'].fields as real Field objects, so they render through the same SDK field components and stay inline-editable. Only children the override needs (rows) take a server-side client.getData.

Two shapes that fail:

  • Placing the block per page in headless-main moves it inside <main>, above the page's last section, and breaks the visual contract.
  • Adding a new page-level placeholder (e.g. headless-footer-page in the layout's <footer>) does not work either. The Layout Service silently drops a placeholder key that is not registered: it is missing from route.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:

  1. Site collection / site nodes (often created at provision time via XM Apps API)
  2. Datasource templates → parameters templates → rendering items (componentName exact)
  3. Available Renderings → page presentation → datasource content → Headless Variants
  4. 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:

  1. Place markup in src/components/<Component>/<Component>.tsx (helpers go in src/lib/<feature>/ or src/app/api/<feature>/ — see content-sdk-component-naming-traps).
  2. Replace plain props with SDK field components: <Text>, <RichText>, <Image>, <Link> — types from node_modules/@sitecore-content-sdk/react .d.ts.
  3. Derive props from the live getPage / layout-debug payload, not from static prop names alone.
  4. Classify resolver pattern (content-sdk-resolver-patterns); decide variant vs sibling (content-sdk-variants-vs-siblings).
  5. Regenerate component map; lint + tsc clean; 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

  1. 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).
  2. Probe before implementing (layout-debug / resolver probe).
  3. Dark+light+system theme is the default head-app theme stack (content-sdk-app-router-theme-hydration-pattern).
  4. Never silently fail on an unexpected Edge shape — capture the payload and escalate.
  5. 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.
  6. 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 implementation text on any route ← the reconciliation
  • every route returns 200, and the final URL is still on the deployment origin
  • nav / main / footer present; nav carries real links, not all href="/"
  • 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 revalidate never 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:

  1. One getLayout(path) (or equivalent) module returning fixtures today / client.getPage tomorrow.
  2. Fixtures shaped as declared Layout types (cite .d.ts).
  3. Quarantine Edge-side SDK calls (getDictionary, getErrorPage, static params) behind one flag in that module.
  4. Document that npm run dev / sitecore-tools:build still hits Edge unless an offline script exists.
  5. Still produce the content-model spec — mock defers provisioning/authoring, it does not cancel it.

Related skills

  • setup-content-sdk — head-app scaffold + env
  • sitecoreai-cli-cloud-workflow — CLI login / ser pull
  • content-sdk-create-component — clone/customize renderings via Authoring GraphQL
  • sitecoreai-edge-graphql-capture — Edge snapshot
  • content-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

More from Chris1415/sitecore-skills-pocs

All 8