I spent this year watching Q&A groups, and a couple of external answer engines, fail in the same way. The model was fine. The index document was a title, a thumbnail, and an empty body. This post is the attribute and extractor work I do before I turn generation on. It is also the part I am willing to call engineering guidance rather than a product feature: nothing in Sitecore's docs says "make your pages citable by any LLM". The docs do say that an answer is only as good as the indexed items, and they return document_id and context with a Q&A hit. Citation, in the product, means pointing at a document you extracted on purpose.

Answers are an index feature

Sitecore's Q&A documentation is specific. You create a question-and-answer group under Administration, Domain Settings, Feature Configuration. The group has a name, one or more sources, an entity, and up to five attributes. Those attributes are what generation is allowed to read. Textual relevance has to be enabled on each of them before you generate. You publish the feature configuration, open the Q&A Browser, and run batch generation. The group gets an rfk_id. That id is what the widget request uses later.

If the source does not contain the fact, the API returns nothing. The same docs state that the feature supports English only. I re-read that page for multilingual sites, because a "currently" in the docs can move. As of the documentation I used for this post, I do not promise French or German answers from the product.

There is a second, quieter constraint. The visitor's keyphrase has to qualify as a question or a statement. A bag of keywords returns an empty Q&A payload even when the index has the document. I have watched teams file this as an API bug after wiring Q&A to the same box that serves keyword search. It is a documented qualification rule. Keyword search and answer generation are different requests. I issue them separately and I render an answer only when the response actually contains one.

Related questions use questions.related_questions.limit. An exact answer uses questions.exact_answer, and the example Sitecore publishes sets query_types to ["statement"]. You can send both in one widget item. The response includes the question, the answer, a context passage, and a document_id. That pair is the citation. I store it. I do not display an answer I cannot trace to a document in the group.

{
  "widget": {
    "items": [
      {
        "entity": "content",
        "rfk_id": "rfkid_product_docs",
        "questions": {
          "keyphrase": "How long does a publish take to reach the CDN?",
          "exact_answer": { "query_types": ["statement"] },
          "related_questions": { "limit": 3 }
        }
      }
    ]
  }
}

The Cloud SDK's server package describes the same request as QuestionsAnswersOptions: a required keyphrase, optional exactAnswer, optional relatedQuestions, optional rule. I keep the Next.js call on the server. An API key that can read the domain does not belong in a browser bundle, and the answer is not a client-side concern until it is HTML I chose to render.

Attributes are the product

Sitecore Search does not search your CMS. It searches index documents, and an index document is a set of attributes. The domain starts with a Content entity and a handful of default attributes. Everything else is one you create under Domain Settings, Attributes, and then extract.

The properties I set deliberately:

• Attribute name. Alphanumeric, underscores, no spaces. This is the key in the extractor and the key in the API response when "return in API response" is on. I treat a rename as a migration. Widgets, sorting options, and Q&A groups all bind to it.
• Data type. The type decides which features light up. A string can be a term facet. A number can be a histogram. A geo value is how I indexed coordinates back in 2024, and it is still a different type from a string that happens to look like "lat,lon".
• Required. If the extractor cannot find a required attribute, Search does not index the item. I mark id, title, url, and type required. I do not mark a nice-to-have badge required, or a single missing badge drops the whole article.
• Default value. Useful for a constant like type=article when the template implies it. Dangerous for description, because a default sentence will be the sentence the model cites.
• Placement. Standard, or Locale when the domain is multilingual. Localized titles overwritten by a single shared value are a quiet relevance bug.

Use-for-features comes after the attribute exists. Textual relevance is configured at the domain and then weighted on the global widget. Sitecore's own guidance is to keep a single attribute's weight at or below 5 so one field does not dominate. I weight title above description, and description above a long content_text, then I look at real queries before I touch the numbers again. Facets have their own settings: aggregation, and/or behavior, order, and a max. The docs warn that alphabetical sorting of a large value set and a max above 50 hurt performance, and that 100 is the ceiling. Q&A does not require every attribute to be a facet. It requires the five you selected to carry text and to have textual relevance on.

A practical set for an article-like page:

That table is my default, not a Sitecore schema. Your entity might be a product, a location, or a document. The rule that travels is: if a human would need the fact in order to trust a quote, extract it as its own attribute. Do not hope the model will recover it from a blob of chrome.

Extractors decide whether the attribute is real

A source is either pull or push. Pull sources are the web crawler, the advanced web crawler, and the API crawler. Push sources take index documents through the Ingestion API. I use push when the content already lives in Sitecore and I can map fields myself. I use a crawler when the HTML is the source of truth, including pages the head application renders from Experience Edge.

The document extractor writes key: value pairs onto the index document. Sitecore's rule for non-JavaScript extractors is that they stop at the first match. A JavaScript extractor runs to the end. If the first h1 on the page is the cookie-banner title, an XPath rule for title will lock onto it and never see the article heading. I either tighten the XPath to the main region or I switch that attribute to JavaScript and ignore the chrome on purpose.

For an advanced web crawler the documented extractor types are XPath, CSS, and JavaScript. An API crawler adds JSONPath. URLs-to-match on a tagger keep a blog extractor off the search page and the cart. Multiple taggers mean multiple sets of documents. I want one tagger per entity, with one rule per attribute, until I have a reason to split.

Validation shows the values a URL would produce and creates nothing. It also does not execute client-side JavaScript. A Next.js page that paints the article in the browser validates as an empty shell. Sitecore's documented workaround is the one I use: turn rendering on, set MAX_URLS low, run the crawler, and read content_text on the indexed document.

Sitemap triggers use lastmod. A sitemap that stamps every URL with the request time forces a full recrawl. Emit the real modification time.

The citation payload I want in every document

This is the engineering guidance, labeled as such. Sitecore Q&A will cite document_id and context because that is the response shape. A third-party answer engine that fetches the public URL will only cite what the HTML contains. I make those two views agree.

For each URL I am willing to have quoted, the HTML and the index document both expose:

• a canonical URL
• one title
• a description that a person could read aloud
• a visible published or updated date
• a stable id I also store in the index
• body text that is present without executing a client-side bundle, where I can manage it

The last bullet is the hard one on a pure client render. If the article body arrives only after hydration, a crawler that is not configured to render JavaScript indexes the shell, and some external fetchers never render at all. I do not have a Sitecore switch that fixes someone else's crawler. The lever I do have is server-rendered HTML for the pages we want discovered, plus an index document we control through a push source if the crawler is the wrong tool.

A push document for the same contract looks like this:

{
  "document": {
    "id": "article-2026-10-27-cache-purge",
    "fields": {
      "type": "article",
      "title": "How long a publish takes to reach the CDN",
      "url": "https://example.com/docs/publish-and-cdn",
      "description": "A publish updates Experience Edge first. The CDN keeps the previous HTML until revalidation or a cache-tag purge runs.",
      "content_text": "Publishing a Sitecore item updates the content delivery API. HTML cached at the CDN stays stale until the site purges the tag for that path.",
      "published_at": "2026-10-27T03:00:00Z",
      "language": "en"
    }
  }
}

example.com is a stand-in, not a client. The body is short on purpose. Q&A was documented to read up to five attributes, not the entire CMS. I would rather extract two tight paragraphs than a 4,000-word page with the header menu concatenated in front of them. Concatenated chrome is how an answer quotes the login link.

A checklist I run before the first batch generation

I keep this next to the source configuration. It is all documented product behavior, in the order that usually hurts.

1. Create the attributes, including url, title, description, and content_text. Mark only the identity fields required.
2. Enable textual relevance on the attributes the Q&A group will use. Weight them on the global widget. Stay at or under a weight of 5 on any single attribute until you have query evidence.
3. Extract them. For a web source, confirm whether the rule is XPath, CSS, or JavaScript, and remember that only the JavaScript rule runs past the first match.
4. Validate a handful of URLs. Then do a rendered crawl with a low MAX_URLS if the site is a JavaScript app. Open an indexed document and read content_text with your eyes.
5. Create the Q&A group, pick the source and the entity, add no more than five attributes, publish feature configuration, and run batch generation. Note the rfk_id.
6. Call the widget with a full question and with a two-word keyword. The question should be eligible for an answer. The keyword should come back empty. If the keyword returns an answer, I do not trust the integration yet and I re-read the qualification note.
7. Render answer together with document_id and the url of that document. An answer with no link is not a citation. It is a paragraph I cannot defend.

The product documentation I am using limits Q&A to English. I still extract language for keyword search, and I do not point the English group at every locale's source.

A clean index does not guarantee that some other assistant will quote the site. That depends on crawlers Sitecore does not operate. Sitecore Search can ground an answer only in attributes you extracted, and the Q&A API returns the document identity and a context passage when it has one. A Next.js page that hides its text in the client feeds both an empty document.

Name the attributes. Extract the words a person would quote. Prove it with a small crawl. Then turn generation on.

The explanation is almost always the same. The agent did what its tools allow, inside the caller's permissions, and wrote Sitecore items. The Next.js app renders only the renderings it was built with, through the fields those renderings read. Agentic Studio does not compile that app. This is the 101 I give developers who are about to be asked to "just add an agent" to an existing SitecoreAI implementation.

Two kinds of custom agent, and only one of them is a workflow

Sitecore's Agentic Studio docs split custom agents by shape.

A standard agent is the chat-style, task-driven one. You reach for it when the user is still deciding what they want, iterating on a brief, or asking for a draft they will edit by hand. It is the closer cousin of the Stream optimize-content panel I wrote about in 2025, except it sits in Agentic Studio and can call SitecoreAI tools rather than only rewriting the field in front of the author.

A workflow agent is for a sequence you can draw. Sitecore recommends it when the outcome should be consistent: a fixed order of steps, approvals, and structured outputs. The workflow editor opens on five tabs. Overview holds the name, the description, and the run-page copy ("what is it for", "how it works") plus the inputs the user must fill in. Parameters, schemas, and HTML templates shape what the agent accepts and how a result is presented. The Workflow tab is the sequence itself.

You need a Builder license to create either kind. I confirm that license before I sit down with a marketer to sketch steps. Duplicating a prebuilt agent is the documented shortcut when the change is small, and an exported JSON definition is a reasonable thing to keep in source control next to the rendering contract it depends on. I do not treat that JSON as a substitute for the Next.js component. It is configuration. The component is code.

A fixed sequence belongs in a workflow agent. A conversation that is still finding the brief belongs in a standard agent.

The tools are Sitecore operations, not React components

Workflow steps do their Sitecore work through the Invoke Tool action. The configuration is three fields: the tool, a Parameters JSON object, and an output variable that stores the response. A successful response carries success: true and a data object. A failure carries success: false and an error string. Some tools nest further, which is why the second step in a flow so often breaks.

Sitecore's own walkthrough chains Search Pages into Get Page Content. Search Pages takes siteName, searchText, language, and pageSize, and each hit includes an itemId. Get Page Content wants that id as pageId. The workflow expression that connects them is not "pass the previous output". You type @ in the Parameters editor, pick the upstream step, and then edit the path until it resolves to the id string alone. A path that resolves to the whole tool payload is a type error the tool will not forgive. The expression in Sitecore's walkthrough names the upstream step and ends at itemId. The step id is generated. The lesson I care about is that last segment: the id, not the envelope.

I redraw that flow for our sites with our site name and a rendering we actually ship:

{
  "siteName": "marketing",
  "searchText": "product overview",
  "language": "en",
  "pageSize": 1
}

The following step may only receive the id:

{
  "pageId": "{{@<generatedStepId>:Find product page.data...itemId}}"
}

I left the middle of the path as data... on purpose. Sitecore's docs say the exact path varies by tool and that you should inspect the previous step's output when a later step fails. Copying a path from a blog, including this one, is how you bind to data.data.data.1 on a tool that returned data.results[0]. Open the step log. Point the expression at the id. Then lock the flow.

The Invoke Tool catalog is wide. The docs group it into site discovery, page management, components, assets, personalization, brand kits, briefs, and experiments, and there is a web_search tool whose sample parameter is a query string. Web search is the one I flag in review. It can pull public pages into a prompt. It must not be the source of record for a claim we then publish on our own site. Our pages, our brand kit, and our indexed content are the sources I want in the flow. The public web is research, and a person should read it before it becomes a field value.

The same operations exist as an API and as an MCP server

Agentic Studio is the UI. The Agent API is the surface underneath it, and it is documented for developers who are not clicking the workflow editor. It is a REST API, called in the production environment, authorized with an automation-client JWT or with an OAuth app. An Organization Admin or Owner creates the automation client under SitecoreAI Deploy, and the client secret is shown once. I store that secret the way I store any other production credential. I do not paste it into a workflow screenshot.

The documented object areas match the tools: sites, pages, content items, components and datasources, assets, environments and languages, personalization variants, jobs, brand kits, brand context, briefs, experiments, and flow definitions for A/B/n tests. Every call still passes through Sitecore's security and approval rules. The detail I make sure our team hears is the job id. If an agent writes the wrong thing, the job id is the handle Sitecore documents for reverting that operation. "The AI did it" is not an audit trail. The job id is.

The Marketer MCP server is the natural-language front door onto those same endpoints. Sitecore documents it as an MCP server that MCP clients such as Claude Desktop and Cursor can use to create pages, place components, and update content. The tool reference says the actions remain subject to the user's permissions and to whatever review, approval, versioning, and publishing workflow the site already has. I like that sentence. It means an MCP client is not a backdoor around the workflow we spent last year putting on the site. It also means a developer with publish rights, pointed at production, can do real damage in one prompt. The automation client should be scoped the way we scope a CI credential, and production prompts belong to people who already understand the site.

I do not wrap the Agent API in a second undocumented facade inside the Next.js app "so the frontend can call agents". The rendering app's job is to read published layout data and draw it. Agent calls belong in a server-side integration with a credential that never reaches the browser, or they belong in Agentic Studio itself. A NEXT_PUBLIC_ secret for the automation client would be a defect, not a shortcut.

The contract I write down before anyone opens the workflow editor

This is the page I want in the repo. It is short because the agent will not read our component source unless we hand it the constraints.

export const productHeroContract = {
  renderingName: 'ProductHero',
  templateId: 'B6C3E0A1-1111-2222-3333-444455556666',
  fields: {
    heading: { type: 'single-line', maxLength: 80 },
    summary: { type: 'multi-line', maxLength: 240 },
    image: { type: 'image', required: true },
    cta: { type: 'general-link' },
  },
} as const;

The GUID above is a placeholder. Yours comes from the template item. The rules I enforce around it:

• The rendering name matches the key in the Content SDK component map, character for character.
• The fields listed are the fields the React component reads. Extra fields are allowed only if a developer has agreed to ignore them on purpose.
• maxLength is a product decision we also enforce in the agent prompt and, where Sitecore validation exists, on the template. The agent will otherwise write a hero headline the length of a blog lede.
• Required image means the flow has to pick an asset from the library or stop. I would rather the step fail than publish a hero with a broken image field.
• Links use the site's link format. A bare https:// string stuffed into a general link field is a classic "the tool returned success and the component rendered nothing" bug.

Schemas and HTML templates in the workflow agent are how Sitecore lets you shape the agent's own output. They are useful for a brief, a tweet, or a summary the user will copy. They are not a second design system. When the output is supposed to land on a page, I prefer Invoke Tool against a known template over an HTML blob the page builder cannot edit properly later.

Where I still want application code

Rendering and design. Layout, responsive behavior, accessibility, and the design system live in the Next.js app. An agent that emits a one-off HTML fragment for a campaign landing page will not pick up the next brand refresh. Pages composed from existing renderings will.

Authoring mode. Content SDK exposes page.mode. Chrome, placeholders, and field metadata are the SDK's job. Our job is to keep custom components from hiding buttons, trapping focus, or rendering a different DOM tree in editing mode than they do on the live site. If the trees diverge, the page builder and the published page drift apart and authors stop trusting both.

Personalization variants that have logic. SitecoreAI can create variants and experiments through the Agent API. The variant is still content. If a variant depends on a claim code, a pricing rule, or a feature flag, that rule stays in code or in the personalization engine we already operate. I do not bury it in a system prompt.

Publishing and cache. A flow that creates a page has not published it unless a publish step ran, and a publish has not updated the CDN unless our revalidation ran. I keep that wiring in the application and in the existing publish hook. Agentic Studio does not know that Netlify, or any other host, keyed the HTML on a cache tag.

Secrets, retries, and idempotency. Workflow tools can fail halfway. I want a flow that searches for the page it might already have created before it creates another one. That is ordinary integration hygiene. The visual editor will not add it unless someone who has been paged for duplicate items insists.

A review I run the first time a flow touches a real site

I ask for a non-production site and a content tree we can delete. Then I walk the flow once and keep the notes.

1. Who can run it, and does that user have publish rights? If they do, say so in the run-page copy. "How it works" is not the place to be vague.
2. Does every Invoke Tool parameter resolve to the scalar the next tool documents, especially ids?
3. Does the created item use a template our component map renders? Open the page builder. If the rendering is unknown, the flow is ahead of the repository.
4. Is there a job id in the run log, and has someone actually reverted a test write with it? I want that rehearsal before the first marketing demo.
5. Did a publish happen, and did the head app show the new field values without a redeploy? If a new rendering was required, the answer is no, and the flow should not pretend otherwise.
6. Are brand-kit and language inputs explicit? Sitecore's November 2025 examples, Berkeley Homes and AFL among them, were about contextually aware content aimed at the right audience and channel. Those were Sitecore's customers in the press release, not a template you can copy. On our sites the brand kit and the language parameter have to be chosen, not assumed.

What I tell a developer who is new to the studio

Learn the five tabs and one chain: Search Pages, then Get Page Content, then a write or a Generate Content step you can read. Learn the @ path rule. Learn where the automation client is stored. Then stop, and go read the component that will render the result.

The prebuilt agents from November 2025 are allowed to be useful without a pull request. Campaign drafts, migration assistance, test ideas: that is the point of shipping twenty of them. The moment a flow creates a rendering, a template, or a field, it has crossed into the application, and the application changes in git. That line is the whole 101. Agents are very good at operating Sitecore. They are not the Sitecore implementation.

The honest answer is that two upgrades got collapsed into one sentence. The SaaS content tenant moved forward without a replatform. The JavaScript stack that renders that tenant has its own lifecycle, and that lifecycle has been moving since the week of the announcement. This post is the map I use with a Next.js team in October 2026, looking back at what was public in November 2025 and what the developer documentation says now.

What November 2025 actually shipped

The 4 November 2025 announcement, published from London, described SitecoreAI as a composable SaaS platform built on XM Cloud and hosted on Microsoft Azure. It unifies content management, customer data, personalization, and search. The new workspace is Agentic Studio. Sitecore said it launched with 20 prebuilt agents covering work from campaign planning through content migration, production, and testing, plus visual tools so marketers and agency partners can design their own agents and flows. Agentic Flows orchestrate multi-step work from briefing and experimentation through publishing. Spaces are the collaboration surface between people and those agents.

The same release named the upgrade path for existing XM Cloud customers: no migration, continuity of data, and access to Agentic Studio and the prebuilt agents. I take that sentence literally. Items, templates, sites, media, and the Experience Edge content the site already reads are not thrown away because the product name changed. When a stakeholder asks me to budget a "SitecoreAI migration" for a healthy XM Cloud implementation, I split the estimate. Tenant continuity is the vendor's claim. Head-application work is ours, and it is a different line item.

Sitecore also framed the product around discovery that happens outside the website: feeds, summaries, and moments where the brand has to show up with a governed message. That framing matters for implementation teams because it pulls Search, brand kits, and the rendering app into one conversation. It does not, by itself, change a getStaticProps function.

A few days before the announcement, the Sitecore developer changelog recorded two SDK facts that are easy to miss if you only read the press release. On 29 October 2025 Sitecore published an SDK lifecycle for XM Cloud: Content SDK 1.x became the actively supported SDK, and JSS support on XM Cloud moved onto a phase-out path. On 30 October 2025 Content SDK 1.2 added Next.js App Router support and shipped it as a beta. Server components, streaming, nested layouts, and fetching layout data from server components were in that beta. Sitecore said the beta was supported for teams who wanted to try it, and that the shape could still change. I treated "try it" as the operative instruction in late 2025. I still treat a router migration as its own project in 2026.

What did not change in the Next.js app on day one

The websites I work on still render Sitecore content through a head application. Pages are still compositions of placeholders and components. Field values still arrive as layout data or as a GraphQL result. Experience Edge is still the delivery API in front of published content. A page that was fast in October 2025 did not become fast because Agentic Studio appeared in the portal, and a page that over-fetched GraphQL did not heal itself either.

Authors still publish. Workflows, if you had them, still gate what Edge will serve. I wrote earlier in 2025 about Stream's optimize-content actions inside the page editor, and about cache tag purge when a publish has to show up on Netlify. Those problems are still implementation problems. SitecoreAI gives authors more ways to draft and to run a governed flow. The CDN in front of the Next.js app does not learn about that flow unless we invalidate it.

Component code remains the contract for anything an agent is allowed to create. If the hero component reads heading, summary, and image, an agent that writes a fourth field into a datasource does not get a new visual. It gets a value the component ignores. I have watched teams discover this the expensive way: a flow "succeeds" in Agentic Studio, the page item exists, and the site renders an empty region because the rendering item or the component map was never part of the flow.

Search stays a configured product. SitecoreAI's story includes search, and the Questions and Answers capability in Sitecore Search is a real, documented feature. Index attributes, document extractors, and widget rfkIds do not reconfigure themselves when the portal is rebranded. I cover that work in the posts later this week. For this one, the point is narrower. Announcement week was not a Search cutover.

What did change for the people who maintain the head

The SDK lifecycle is the change I plan against. JSS carried XM Cloud sites for years, including the multisite Next.js apps most of us still have in production. Sitecore's own position, written into the October 2025 lifecycle note and repeated in the Content SDK upgrade guides, is that one JavaScript SDK should not keep serving two diverging runtimes. Content SDK is the SDK for SitecoreAI. It drops Experience Editor chromes, generates a component map instead of the old component builder, and funnels data access through SitecoreClient.

By October 2026 the upgrade guide I hand a team is the Content SDK 2.1 guide for a JSS 22.0 Next.js app. That guide expects Next.js 16, React 19, sitecore.config.ts, sitecore.cli.config.ts, and a defineProxy helper, because Next.js 16 runs proxy.ts. Content SDK 1.5 and earlier called the same idea defineMiddleware. Match the guide to the package version you install, and trust the create-content-sdk-app scaffold when a checklist still says only middleware.ts.

Editing changed in a way authors notice before developers do. Content SDK does not support the Experience Editor, and it does not support preview opened from the Content Editor. Preview and visual editing go through the SitecoreAI page builder, using metadata on the fields. field.editable is gone. Field components read field.metadata. pageState, pageEditing, and renderingType on the layout context fold into page.mode, with flags such as isEditing, isPreview, isNormal, and isDesignLibrary. Any component that branched on the old context properties still compiles only if nobody deleted the property access. Once the import moves to @sitecore-content-sdk/nextjs, those branches fail, or worse, they silently stop wrapping the authoring chrome.

Environment names moved with the SDK. The 2.1 guide renames SITECORE_API_KEY to NEXT_PUBLIC_SITECORE_API_KEY, SITECORE_API_HOST to NEXT_PUBLIC_SITECORE_API_HOST, SITECORE_SITE_NAME to NEXT_PUBLIC_DEFAULT_SITE_NAME, DEFAULT_LANGUAGE to NEXT_PUBLIC_DEFAULT_LANGUAGE, and JSS_EDITING_SECRET to SITECORE_EDITING_SECRET. SITECORE_EDGE_URL is replaced by NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME on Next.js so the client bundle and the server agree. DISABLE_SSG_FETCH becomes GENERATE_STATIC_PATHS, and the meaning is inverted. I have seen a pipeline "succeed" with an empty static path list because someone copied true from the old variable into the new one.

Logging into Agentic Studio in November 2025 did not require any of it. Picking up the SDK Sitecore is supporting now does.

How I separate the work

I keep four buckets on the board. Mixing them is how a two-week authoring rollout becomes a quarter-long rewrite.

1. Tenant continuity. Confirm the organization is on SitecoreAI, Agentic Studio is visible to the roles that need it, and existing sites still resolve. This is mostly an admin and smoke-test exercise. Sitecore's November 2025 statement was that XM Cloud customers do not migrate content to get there.

2. Authoring and agents. Brand kits, prebuilt agents, and any custom workflow agent. Custom agents need a Builder license, which is documented on the create-a-workflow-agent page. This bucket changes the portal. It should only create pages and content that the current component set already understands.

3. The rendering app. Content SDK, on the version you can support, Pages Router first if that is what production runs. App Router support shipped as a beta in Content SDK 1.2 at the end of October 2025. I still schedule that router move separately from the package swap.

4. Discovery. Sitecore Search attributes, extractors, and the Questions and Answers group if you want answers grounded in your index. That work pays off the "world beyond the website" line in the press release. It is not a side effect of installing Content SDK.

A small guard I add in the Next.js app

Agents and the page builder both end up calling the same renderings. The guard I want is boring. It asks two questions: are we in an authoring mode the page builder understands, and is every rendering name present in the component map the build generated?

type PageMode = {
  isEditing?: boolean;
  isPreview?: boolean;
  isNormal?: boolean;
  isDesignLibrary?: boolean;
};

export function isAuthoringMode(mode: PageMode | undefined): boolean {
  return Boolean(mode?.isEditing || mode?.isPreview || mode?.isDesignLibrary);
}

export function assertKnownRendering(
  componentName: string,
  componentMap: Record<string, unknown>
): void {
  if (!componentMap[componentName]) {
    throw new Error(
      `Rendering "${componentName}" is not in the Content SDK component map. ` +
        `An agent or the page builder can place it only after the Next.js app registers it.`
    );
  }
}

page.mode is the Content SDK shape. The throw is my choice. The SDK's usual behavior for an unknown rendering is to render a fallback, which is friendlier in production and useless in a migration branch. I fail the authoring build so a new agent flow cannot ship a rendering the repository has never heard of.

The matching config check is about Edge, not about agents. After the environment rename, a Next.js app should resolve the platform host from the public variable and fall back to Sitecore's default only when nobody has set one:

const edgeUrl =
  process.env.NEXT_PUBLIC_SITECORE_EDGE_PLATFORM_HOSTNAME ||
  'https://edge-platform.sitecorecloud.io';

That default is the one the Content SDK 2.1 guide documents. If your tenant uses a custom Edge hostname, the public variable has to be present at build time. Next.js inlines NEXT_PUBLIC_* then. A runtime-only secret with the old SITECORE_EDGE_URL name will not reach the client, and preview will look randomly broken depending on which side issued the request.

What I refuse to put in the same sprint

I do not schedule a head rewrite because the product brochure changed. The November 2025 promise to XM Cloud customers was continuity. Spending that continuity on a from-scratch App Router app throws away the part that was actually seamless.

I do not let a workflow agent create templates. The Next.js component and the GraphQL selection are compiled. An agent can fill fields, place a rendering that already exists, and start an experiment. The Agent API documents job ids so a bad write can be reverted. Search Q&A stays a separate piece of work: generation only sees attributes you extracted, and extractor validation does not execute client-side JavaScript.

A sequence that has survived contact with a real backlog

This is the order I recommend when the site is already on XM Cloud and SitecoreAI is in the portal. It is an implementation sequence, not a Sitecore-mandated program.

1. Smoke-test the existing site, the page builder, and one prebuilt agent on a non-production site. Confirm a publish still reaches Edge and that cache purge still fires.
2. Inventory JSS: package names, temp/config, page-props plugins, and every read of field.editable.
3. Pick one Content SDK version and read only that upgrade guide. In October 2026, for a JSS 22 app that can take Next.js 16, that is the 2.1 guide. Stay on the Pages Router for the first merge.
4. Generate the component map in CI with sitecore-tools before next build.
5. Design custom agents after that, using rendering and field names from the inventory, a Builder license, and a rollback drill with the Agent API job id.
6. Schedule App Router and Search Q&A as follow-on work with their own test plans.

Documentation I kept open

• Sitecore's 4 November 2025 press release, "Sitecore Unveils SitecoreAI".
• Sitecore developer changelog, 29 October 2025, "New SDK lifecycle introduced for XM Cloud".
• Sitecore developer changelog, 30 October 2025, "Content SDK v1.2 — App Router support".
• Sitecore documentation, "Upgrade JSS 22.0 Next.js apps to Content SDK 2.1", which is the guide I am using in October 2026.
• The Agentic Studio and Agent API docs, for the boundary between a flow and the rendering app. The next post goes into that boundary in detail.

The platform move was real in November 2025, and for an XM Cloud customer it was mostly a portal change. The Next.js change is real too. It shows up when you leave JSS, when you follow page builder metadata, and when you stop assuming an agent understands a component you have not registered. Those are the items I put on the board. The product rename is not one of them.

I'll walk you through how we solved this by combining Next.js ISR revalidation with Netlify's cache tag purge API. We also leverage a Sitecore PowerShell script that triggers the endpoint for selected pages or items directly from the Content Editor. It's a pretty straightforward approach once you understand how Netlify's caching works.

The Problem

When we deployed our Next.js app with ISR to Netlify, we quickly noticed something wasn't right. Pages were staying cached at the edge even after we triggered revalidation. Here's what was happening:

• Stale Content: Authors would publish updates in Sitecore and trigger revalidation, but users kept seeing the old version for way too long.
• ISR Limitations: The res.revalidate(path) method that works great on Vercel doesn't always make it through Netlify's edge network. It's hit or miss.
• No Granular Control: Without cache tags, we couldn't target specific pages. Our options were basically "purge everything" or "wait for the cache to expire" - neither is ideal.
• Author Experience: Content authors started losing trust in the system. They'd constantly refresh to see if their changes were live, which led to support tickets and manual cache clearing.

Netlify's edge caching is great for performance, but it works differently than what we were used to. We needed to work with Netlify's system, not against it.

The Solution

We ended up with a three-part solution that plays nicely with Netlify's caching:

1. Middleware Cache Tagging: We use Next.js middleware to stamp every HTML route with a Netlify-Cache-Tag header. This happens automatically before the page gets cached, so each page has a unique identifier.

2. Revalidation API: Our /api/revalidate endpoint tries the standard Next.js ISR revalidation first (just in case it works), then calls Netlify's purge API with the matching cache tag. This way we cover both bases.

3. Sitecore Integration: A simple PowerShell script in Sitecore calls our revalidation API when content gets published. Authors don't have to change their workflow at all.

Here's the decision flow:

Request for /en/products/abc
         └─> Middleware intercepts
         |   └─> Builds cache tag: page:en_products_abc
         |   └─> Sets Netlify-Cache-Tag header
         |   └─> Page cached with tag
         |
Content author publishes in Sitecore
         └─> PowerShell script executes
         |   └─> POST to /api/revalidate
         |       └─> Verify secret
         |       └─> Try res.revalidate(path) (best-effort)
         |       └─> Build matching cache tag
         |       └─> Call Netlify purge API with tag
         |       └─> Netlify invalidates page across CDN

This gives us the best of both worlds: we keep the performance benefits of edge caching, but we can also invalidate specific pages whenever we need to. The cache tag system is the key - it lets us target exactly what we want to clear.

How It Works

Let me break down the code so you can see how everything fits together.

middleware.ts - Cache Tag Stamping

This is where it all starts. The middleware runs before any page is rendered and stamps each route with a cache tag.

File Name & Role: middleware.ts (root of your Next.js app). This middleware intercepts requests and adds cache tag headers to HTML routes, so Netlify knows which tag belongs to which page.

What it exports:

• middleware: The main function that processes requests
• buildCacheTag: A helper that converts paths into cache tag format

Code:

import type { NextRequest } from 'next/server';
import { NextResponse } from 'next/server';

function buildCacheTag(path: string): string {
  if (!path || path === '/') {
    return 'page:home';
  }

  const normalized = path
    .trim()
    .replace(/^\/+|\/+$/g, '')
    .replace(/\//g, '_')
    .replace(/[^a-zA-Z0-9_-]/g, '');

  return `page:${normalized || 'home'}`;
}

export function middleware(req: NextRequest) {
  const pathname = req.nextUrl.pathname;

  if (
    pathname.startsWith('/api') ||
    pathname.startsWith('/_next') ||
    pathname.startsWith('/favicon') ||
    pathname.match(/\.(ico|png|jpg|jpeg|gif|webp|svg|css|js|txt|xml)$/)
  ) {
    return NextResponse.next();
  }

  const res = NextResponse.next();
  const cacheTag = buildCacheTag(pathname);

  res.headers.set('Netlify-Cache-Tag', cacheTag);
  res.headers.set('Cache-Tag', cacheTag);

  return res;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|api).*)'],
};

Why this works:

• Automatic Tagging: Every HTML route gets tagged automatically, so you don't have to think about it. It just works.
• Normalization: The buildCacheTag function turns paths like /en/products/abc into page:en_products_abc. This makes the tags predictable and URL-safe, and they match what we use in the revalidation API.
• Selective Application: We skip API routes, Next.js internals, and static files - they don't need cache tags anyway.
• Dual Headers: We set both Netlify-Cache-Tag and Cache-Tag headers. Netlify uses the first one, but the second is a standard that other CDNs recognize too, so you're covered if you switch platforms later.

pages/api/revalidate.ts - Revalidation + Purge

This is where the magic happens. The endpoint tries Next.js ISR revalidation first, then calls Netlify's purge API.

File Name & Role: pages/api/revalidate.ts. This API route handles revalidation requests from Sitecore. It tries ISR revalidation (just in case), then purges Netlify's cache using the cache tag.

What it exports:

• handler: The main API route handler
• RevalidateRequest: TypeScript interface for the request body
• buildCacheTag: Same helper function as the middleware - the logic has to match exactly

Code:

import type { NextApiRequest, NextApiResponse } from 'next';

export interface RevalidateRequest {
  url?: string;
  secret?: string;
  siteName?: string;
}

function buildCacheTag(path: string): string {
  if (!path || path === '/') {
    return 'page:home';
  }

  const normalized = path
    .trim()
    .replace(/^\/+|\/+$/g, '')
    .replace(/\//g, '_')
    .replace(/[^a-zA-Z0-9_-]/g, '');

  return `page:${normalized || 'home'}`;
}

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const revalidateRequest = req.body as RevalidateRequest;
  let revalidated = false;

  if (revalidateRequest.secret !== process.env.REVALIDATE_SECRET) {
    return res.status(401).end('Unauthorized');
  }

  let pathToClear = '/';
  if (revalidateRequest?.url) {
    pathToClear = revalidateRequest.url;
  }

  if (!pathToClear) {
    return res.status(400).end('Revalidated : false');
  }

  try {
    await res.revalidate(pathToClear);
    revalidated = true;
  } catch (err) {
    // Continue with Netlify purge
  }

  try {
    const cacheTag = buildCacheTag(pathToClear);
    const siteId = process.env.NETLIFY_SITE_ID;
    const siteSlug = process.env.NETLIFY_SITE_SLUG;
    const token = process.env.NETLIFY_PAT;

    if (!token || (!siteId && !siteSlug)) {
      return res.status(200).end('Revalidated : ' + revalidated);
    }

    const body: Record<string, unknown> = {
      cache_tags: [cacheTag],
    };

    if (siteId) {
      body.site_id = siteId;
    }

    if (siteSlug) {
      body.site_slug = siteSlug;
    }

    const purgeResp = await fetch('https://api.netlify.com/api/v1/purge', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`,
      },
      body: JSON.stringify(body),
    });

    if (!purgeResp.ok) {
      const text = await purgeResp.text();
      throw new Error(`Netlify purge failed: ${purgeResp.status} ${text}`);
    }
  } catch (err) {
    // Continue even if purge fails
  }

  return res.status(200).end('Revalidated : ' + revalidated);
}

Why this works:

• Dual Strategy: We try both ISR revalidation and Netlify purge. If one fails, the other might still work, so we're covered either way.
• Tag Matching: The buildCacheTag function uses the exact same logic as the middleware. This is crucial - the tag we purge has to match the tag that was set when the page was cached.
• Graceful Degradation: If Netlify config is missing, we still try ISR revalidation and return success. Better than breaking the authoring workflow.
• Security: The secret check keeps unauthorized people from clearing your cache.

Sitecore PowerShell Script

This PowerShell script hooks into Sitecore's context menu to trigger revalidation when content gets published.

File Name & Role: Sitecore PowerShell script (Context Menu). Authors right-click an item in Sitecore and select the revalidation option, which runs this script.

Code:

function ClearCacheForItem {
    Param ([Sitecore.Data.Items.Item]$item)
    
    $siteResolver = [Sitecore.DependencyInjection.ServiceLocator]::ServiceProvider.GetService([Sitecore.Sites.IItemSiteResolver])
    
    $defaultSiteInfo = $null
    foreach ($language in $item.Languages) {
        $langItem = Get-Item -Path "master:" -ID $item.ID -Language $language -ErrorAction SilentlyContinue
        if ($langItem -ne $null -and $langItem.Versions.Count -gt 0) {
            $testSiteInfo = $siteResolver.ResolveSite($langItem)
            if ($testSiteInfo -ne $null -and $testSiteInfo.TargetHostName -ne $null -and $testSiteInfo.TargetHostName -ne "") {
                $defaultSiteInfo = $testSiteInfo
                break
            }
        }
    }
    
    if ($defaultSiteInfo -eq $null) {
        Write-Host "ERROR: Could not find valid site information." -ForegroundColor Red
        return
    }
    
    foreach ($lang in $item.Languages) {
        $languageItem = Get-Item -Path "master:" -ID $item.ID -Language $lang
        if ($languageItem.Versions.Count -eq 0 -or $languageItem.Visualization.Layout -eq $null) {
            continue
        }
        
        $siteInfo = $siteResolver.ResolveSite($languageItem)
        if ($siteInfo -eq $null -or $siteInfo.TargetHostName -eq $null -or $siteInfo.TargetHostName -eq "") {
            $siteInfo = $defaultSiteInfo
        }
        
        $scheme = if ($siteInfo.Scheme) { $siteInfo.Scheme } else { "https" }
        $cleanHostName = $siteInfo.TargetHostName
        if ($cleanHostName.StartsWith("www.")) {
            $cleanHostName = $cleanHostName.Substring(4)
        }
        $siteBaseUrl = "$scheme://$cleanHostName"
        
        $siteContext = New-Object Sitecore.Sites.SiteContext $siteInfo
        $options = New-Object Sitecore.Links.UrlOptions
        $options.AlwaysIncludeServerUrl = $false
        $options.Language = $lang
        $options.SiteResolving = $true
        $options.Site = $siteContext
        $options.LanguageEmbedding = [Sitecore.Links.LanguageEmbedding]::Always
        
        $itemUrl = [Sitecore.Links.LinkManager]::GetItemUrl($languageItem, $options)
        $itemRelativeUrl = $itemUrl
        
        if ($itemUrl.Contains($siteInfo.TargetHostName)) {
            $itemRelativeUrl = $itemUrl.Substring($itemUrl.IndexOf($siteInfo.TargetHostName) + $siteInfo.TargetHostName.Length)
        }
        
        $revalidatePostUrl = "$siteBaseUrl/api/revalidate"
        $body = @{
            url = $itemRelativeUrl
            secret = "YOUR_REVALIDATE_SECRET"
            siteName = $siteInfo.Name
        } | ConvertTo-Json
        
        try {
            $response = Invoke-RestMethod -Uri $revalidatePostUrl -Method Post -Body $body -ContentType "application/json"
            Write-Host "Response: $response" -ForegroundColor Green
        } catch {
            Write-Host "ERROR: Failed to invalidate URL: $($_.Exception.Message)" -ForegroundColor Red
        }
    }
}

$item = Get-Item -Path .
ClearCacheForItem -item $item

Why this works:

• The script automatically triggers cache invalidation when content is published.
• It handles multiple sites and languages without any extra work.
• If something goes wrong, it logs the error but doesn't break the authoring experience.

Getting Started

Here's what you need to do to get this set up:

1. Add Middleware: Create middleware.ts in the root of your Next.js app. This automatically stamps cache tags on all HTML routes.

2. Create Revalidation API: Add pages/api/revalidate.ts with the revalidation logic that calls Netlify's purge API.

3. Configure Environment Variables: In Netlify, add these environment variables:

   • REVALIDATE_SECRET: A secure secret for API authentication
   • NETLIFY_PAT: Your Netlify Personal Access Token
   • NETLIFY_SITE_ID or NETLIFY_SITE_SLUG: Your Netlify site identifier

4. Update PowerShell Script: Replace your existing Sitecore PowerShell script with the version above, and update the REVALIDATE_SECRET value.

5. Test It Out:

   • Publish a page in Sitecore
   • Trigger revalidation via the context menu
   • Check that the page gets purged from Netlify's cache within a few seconds
   • Verify in Netlify's dashboard that cache tag purges are happening

6. Keep an Eye on It: Watch for any edge cases with path normalization or cache tag matching. You might need to tweak the buildCacheTag function based on your URL structure.

That's it! You'll have a cache invalidation system that works with Netlify's edge network while keeping all the performance benefits of CDN caching.

While SAP CDC is a powerful CIAM platform, integrating it with Next.js and Sitecore presented several unique challenges—from JWT verification complexities to session persistence issues and middleware configuration. This post documents the complete implementation, the challenges we encountered, and how we solved them.

Architecture Overview

The authentication flow combines SAP CDC's CIAM platform with NextAuth.js to provide JWT-based authentication for our Sitecore application. Here's how it works:

1. User Authentication: Users authenticate through SAP CDC's screen-sets (customizable login UI)
2. JWT Generation: SAP CDC generates a JWT token after successful authentication
3. Token Verification: NextAuth verifies the JWT using SAP CDC's public key
4. Session Management: NextAuth creates and manages server-side sessions
5. Route Protection: Next.js middleware protects Sitecore routes based on session state

This approach allows us to leverage SAP CDC's authentication capabilities while maintaining compatibility with Sitecore's headless architecture and Next.js routing.

The Challenges We Faced

Challenge 1: JWT Verification with Dynamic Public Keys

Problem: SAP CDC uses RSA256 JWT tokens, but the public key must be fetched dynamically from their API. Initially, we tried to cache the public key, but this caused issues when SAP CDC rotated keys.

Solution: We implemented a JWT verification system that fetches the public key on-demand and handles key rotation gracefully:

async verifyIdToken(idToken: string) {
  try {
    // Fetch SAP CDC public key dynamically
    const gigyaUsApiBaseUrl = process.env.NEXT_PUBLIC_GIGYA_US_API_BASE_URL || 'https://accounts.us1.gigya.com';
    const pubKeyResp = await fetch(
      `${gigyaUsApiBaseUrl}/accounts.getJWTPublicKey?apiKey=${process.env.NEXT_PUBLIC_GIGYA_API_KEY}&format=json`
    );
    const pubKeyData = await pubKeyResp.json();

    if (pubKeyData.errorCode && pubKeyData.errorCode !== 0) {
      throw new Error('Failed to fetch SAP CDC public key');
    }

    const { n, e } = pubKeyData;
    if (!n || !e) throw new Error('Public key data is incomplete');

    // Verify JWT using jose library
    const jwk = { kty: 'RSA', n, e };
    const key = await jose.importJWK(jwk, 'RS256');
    const { payload } = await jose.jwtVerify(idToken, key);

    return payload;
  } catch (error) {
    console.error('SAP CDC JWT verification failed:', error);
    throw error;
  }
}

Challenge 2: Session Persistence Across Page Reloads

Problem: Users were being logged out on page refresh, even though their SAP CDC session was still valid. The issue was that NextAuth wasn't properly syncing with the SAP CDC session state.

Solution: We implemented a session verification mechanism that checks SAP CDC session status before showing the login screen:

function verifyGigyaSession(): Promise<boolean> {
  return new Promise((resolve) => {
    const w = window as any;
    if (!w.gigya?.accounts?.getAccountInfo) return resolve(false);
    
    w.gigya.accounts.getAccountInfo({
      callback: (res: any) => resolve(res.errorCode === 0),
    });
  });
}

Then in the login page, we check for existing sessions before showing the login form:

useEffect(() => {
  loadGigyaScript()
    .then(async () => {
      const hasSession = await verifyGigyaSession();

      if (hasSession) {
        // User already has SAP CDC session, establish NextAuth session
        const w = window as any;
        w.gigya?.accounts?.getJWT({
          fields: 'profile,email,emails,data',
          expiration: 600,
          callback: async (jwtRes: any) => {
            if (jwtRes.errorCode === 0 && jwtRes.id_token) {
              const result = await establishAppSession(jwtRes.id_token);
              if (result.ok) {
                window.location.href = callbackUrl || '/my-account';
              }
            }
          },
        });
        return;
      }

      showScreenSet();
    });
}, []);

Challenge 3: Middleware Route Protection

Problem: Protecting Sitecore routes with middleware while maintaining compatibility with Sitecore's JSS middleware was tricky. We needed to ensure authentication checks happened at the right time without breaking Sitecore's routing.

Solution: We created a middleware that runs after Sitecore's JSS middleware and checks for authentication tokens:

export async function middleware(req: NextRequest) {
  const pathname = req.nextUrl.pathname;

  // Define protected Sitecore routes
  const protectedRoutes = ['/my-account', '/profile', '/settings'];

  const isProtectedRoute = protectedRoutes.some(route => pathname.startsWith(route));

  if (isProtectedRoute) {
    const token = await getToken({
      req,
      secret: process.env.NEXTAUTH_SECRET,
    });

    if (!token) {
      const url = req.nextUrl.clone();
      url.pathname = '/login';
      url.searchParams.set('callbackUrl', pathname);
      return NextResponse.redirect(url);
    }
  }

  return NextResponse.next();
}

Challenge 4: SDK Loading Race Conditions

Problem: The SAP CDC SDK is loaded asynchronously, and we were trying to use it before it was ready, causing "gigya is not defined" errors.

Solution: We implemented a proper SDK loading mechanism with Promise-based initialization:

function loadGigyaScript() {
  return new Promise<void>((resolve, reject) => {
    if ((window as any).gigya) return resolve();
    
    const script = document.createElement('script');
    const gigyaCdnBaseUrl = process.env.NEXT_PUBLIC_GIGYA_CDN_BASE_URL || 'https://cdns.us1.gigya.com';
    script.src = `${gigyaCdnBaseUrl}/js/gigya.js?apiKey=${GIGYA_API_KEY}`;
    script.async = true;
    script.onload = () => resolve();
    script.onerror = () => reject(new Error('Failed to load SAP CDC SDK'));
    document.body.appendChild(script);
  });
}

Challenge 5: Logout Synchronization

Problem: Logging out from NextAuth didn't clear the SAP CDC session, and vice versa, leading to inconsistent authentication state.

Solution: We created a unified logout function that clears both sessions:

export async function logoutFromGigya(): Promise<void> {
  return new Promise<void>((resolve) => {
    try {
      const gigyaWindow = window as any;
      if (typeof window !== 'undefined' && gigyaWindow?.gigya?.accounts?.logout) {
        gigyaWindow.gigya.accounts.logout({
          callback: () => {
            console.log('SAP CDC logout successful');
            resolve();
          },
        });
      } else {
        resolve();
      }
    } catch (error) {
      console.error('Error during SAP CDC logout:', error);
      resolve();
    }
  });
}

// In logout component
const handleSignOut = async () => {
  await logoutFromGigya();  // Clear SAP CDC session first
  await signOut({ callbackUrl: '/login', redirect: false });
  window.location.href = '/login';
};

Prerequisites

What you need:

• Sitecore XM Cloud instance with JSS Next.js app
• SAP CDC account (API Key, User Key, Secret Key)
• Node.js 18+, Next.js 14+

Get your SAP CDC credentials:

1. Log into SAP CDC Console → Admin → Site Settings → API Keys
2. Note your API Key, User Key, and Secret Key

Implementation Guide

Step 1: Install Dependencies

npm install next-auth jose

Step 2: Configure Environment Variables

Create .env.local in your Sitecore Next.js app root:

# NextAuth (generate secret: openssl rand -base64 32)
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_secret_here
NEXTAUTH_JWT_SECRET=your_jwt_secret_here

# SAP CDC Public (from SAP CDC Console)
NEXT_PUBLIC_GIGYA_API_KEY=your_api_key
NEXT_PUBLIC_GIGYA_SCREENSET=Default-RegistrationLogin
NEXT_PUBLIC_GIGYA_START_SCREEN=gigya-login-screen

# SAP CDC Data Center (adjust us1/eu1/au1 based on region)
NEXT_PUBLIC_GIGYA_CDN_BASE_URL=https://cdns.us1.gigya.com
NEXT_PUBLIC_GIGYA_API_BASE_URL=https://accounts.gigya.com
NEXT_PUBLIC_GIGYA_US_API_BASE_URL=

# SAP CDC Private (server-side only - KEEP SECRET)
GIGYA_USER_KEY=your_user_key
GIGYA_SECRET=your_secret

# Optional
NEXT_PUBLIC_SESSION_TIMEOUT_MINUTES=30

⚠️ Important: Add .env.local to .gitignore!

Step 3: Extend NextAuth Types

Create src/types/next-auth.d.ts:

import { DefaultSession } from 'next-auth';

declare module 'next-auth' {
  interface Session extends DefaultSession {
    gigyaProfile?: Record<string, unknown>;
    cardNumber?: string;  // Replace with your Sitecore user identifier
    gigyaToken?: string;
    isFirstLogin?: boolean;
  }

  interface User {
    gigyaProfile?: Record<string, unknown>;
    cardNumber?: string;
    gigyaToken?: string;
    isFirstLogin?: boolean;
  }
}

declare module 'next-auth/jwt' {
  interface JWT {
    gigyaProfile?: Record<string, unknown>;
    cardNumber?: string;
    gigyaToken?: string;
    isFirstLogin?: boolean;
  }
}

Step 4: Create SAP CDC Service

Create src/lib/gigya/gigya-service.ts:

/* eslint-disable @typescript-eslint/no-explicit-any */

interface GigyaConfig {
  apiKey: string;
  userKey: string;
  secret: string;
}

interface GigyaAccountInfo {
  UID: string;
  profile?: { firstName?: string; lastName?: string; email?: string };
  data?: { CardNumber?: string; FirstLogin?: boolean };  // Adjust for your Sitecore schema
  loginIDs?: { emails?: string[] };
  errorCode?: number;
  errorMessage?: string;
}

class GigyaService {
  private config: GigyaConfig;

  constructor(config: GigyaConfig) {
    this.config = config;
  }

  async getAccountInfo(uid: string): Promise<GigyaAccountInfo | null> {
    try {
      const formData = new URLSearchParams();
      formData.append('apiKey', this.config.apiKey);
      formData.append('userKey', this.config.userKey);
      formData.append('secret', this.config.secret);
      formData.append('UID', uid);
      formData.append('include', 'emails,data,profile,loginIDs');

      const gigyaApiBaseUrl = process.env.NEXT_PUBLIC_GIGYA_API_BASE_URL || 'https://accounts.gigya.com';
      const response = await fetch(`${gigyaApiBaseUrl}/accounts.getAccountInfo`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: formData,
      });

      const result = await response.json();
      if (result.errorCode !== 0) throw new Error(`SAP CDC error: ${result.errorMessage}`);
      return result;
    } catch (error) {
      console.error('Error getting SAP CDC account info:', error);
      return null;
    }
  }

  async getJWT(uid: string, fields: string = 'data.CardNumber'): Promise<string | null> {
    try {
      const formData = new URLSearchParams();
      formData.append('apiKey', this.config.apiKey);
      formData.append('userKey', this.config.userKey);
      formData.append('secret', this.config.secret);
      formData.append('targetUID', uid);
      formData.append('fields', fields);

      const gigyaApiBaseUrl = process.env.NEXT_PUBLIC_GIGYA_API_BASE_URL || 'https://accounts.gigya.com';
      const response = await fetch(`${gigyaApiBaseUrl}/accounts.getJWT`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: formData,
      });

      const result = await response.json();
      if (result.errorCode !== 0) throw new Error(`SAP CDC error: ${result.errorMessage}`);
      return result.id_token;
    } catch (error) {
      console.error('Error getting SAP CDC JWT:', error);
      return null;
    }
  }

  async setAccountInfo(uid: string, data: any): Promise<boolean> {
    try {
      const formData = new URLSearchParams();
      formData.append('apiKey', this.config.apiKey);
      formData.append('userKey', this.config.userKey);
      formData.append('secret', this.config.secret);
      formData.append('UID', uid);
      formData.append('data', JSON.stringify(data));

      const gigyaApiBaseUrl = process.env.NEXT_PUBLIC_GIGYA_API_BASE_URL || 'https://accounts.gigya.com';
      const response = await fetch(`${gigyaApiBaseUrl}/accounts.setAccountInfo`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: formData,
      });

      const result = await response.json();
      if (result.errorCode !== 0) throw new Error(`SAP CDC error: ${result.errorMessage}`);
      return true;
    } catch (error) {
      console.error('Error setting SAP CDC account info:', error);
      return false;
    }
  }
}

// Singleton instance
let gigyaServiceInstance: GigyaService | null = null;

export function getGigyaService(): GigyaService {
  if (!gigyaServiceInstance) {
    gigyaServiceInstance = new GigyaService({
      apiKey: process.env.NEXT_PUBLIC_GIGYA_API_KEY || '',
      userKey: process.env.GIGYA_USER_KEY || '',
      secret: process.env.GIGYA_SECRET || '',
    });
  }
  return gigyaServiceInstance;
}

// Client-side logout helper
export async function logoutFromGigya(): Promise<void> {
  return new Promise<void>((resolve) => {
    try {
      const gigyaWindow = window as any;
      if (typeof window !== 'undefined' && gigyaWindow?.gigya?.accounts?.logout) {
        gigyaWindow.gigya.accounts.logout({
          callback: () => {
            console.log('SAP CDC logout successful');
            resolve();
          },
        });
      } else {
        resolve();
      }
    } catch (error) {
      console.error('Error during SAP CDC logout:', error);
      resolve();
    }
  });
}

export default GigyaService;

Step 5: Create Custom NextAuth Provider

Create src/pages/api/auth/[...nextauth].ts:

/* eslint-disable @typescript-eslint/no-explicit-any */
import { getGigyaService } from '@/lib/gigya/gigya-service';
import * as jose from 'jose';
import { NextApiRequest, NextApiResponse } from 'next';
import NextAuth, { NextAuthOptions } from 'next-auth';

// Custom SAP CDC Provider for Sitecore
const GigyaProvider = {
  id: 'gigya',
  name: 'SAP Customer Data Cloud',
  type: 'credentials' as const,
  credentials: {
    id_token: { label: 'ID Token', type: 'text' },
  },

  async verifyIdToken(idToken: string) {
    try {
      // Fetch SAP CDC public key
      const gigyaUsApiBaseUrl = process.env.NEXT_PUBLIC_GIGYA_US_API_BASE_URL || 'https://accounts.us1.gigya.com';
      const pubKeyResp = await fetch(
        `${gigyaUsApiBaseUrl}/accounts.getJWTPublicKey?apiKey=${process.env.NEXT_PUBLIC_GIGYA_API_KEY}&format=json`
      );
      const pubKeyData = await pubKeyResp.json();

      if (pubKeyData.errorCode && pubKeyData.errorCode !== 0) {
        throw new Error('Failed to fetch SAP CDC public key');
      }

      const { n, e } = pubKeyData;
      if (!n || !e) throw new Error('Public key data is incomplete');

      // Verify JWT
      const jwk = { kty: 'RSA', n, e };
      const key = await jose.importJWK(jwk, 'RS256');
      const { payload } = await jose.jwtVerify(idToken, key);

      return payload;
    } catch (error) {
      console.error('SAP CDC JWT verification failed:', error);
      throw error;
    }
  },

  async authorize(credentials: any) {
    try {
      if (!credentials?.id_token) {
        throw new Error('No ID token provided');
      }

      const payload = await this.verifyIdToken(credentials.id_token);
      const uid = String(payload.sub || payload.uid || '');

      if (!uid) throw new Error('Invalid user ID in token');

      // Get user info from SAP CDC
      const gigyaService = getGigyaService();
      const accountInfo = await gigyaService.getAccountInfo(uid);

      if (!accountInfo) throw new Error('Failed to get SAP CDC account info');

      // Get or generate user identifier (adjust for your Sitecore setup)
      let cardNumber = accountInfo.data?.CardNumber || '';
      if (!cardNumber) {
        cardNumber = `TEMP_${uid.substring(0, 8).toUpperCase()}`;
        await gigyaService.setAccountInfo(uid, { CardNumber: cardNumber });
      }

      return {
        id: uid,
        email: accountInfo.profile?.email || '',
        name: accountInfo.profile?.firstName || '',
        gigyaProfile: payload,
        cardNumber: cardNumber,
      };
    } catch (error) {
      console.error('SAP CDC authorization failed:', error);
      return null;
    }
  },
};

// NextAuth configuration for Sitecore
export const authOptions: NextAuthOptions = {
  providers: [GigyaProvider as any],
  session: {
    strategy: 'jwt',
    maxAge: 30 * 60, // 30 minutes
  },
  pages: {
    signIn: '/login',
  },
  callbacks: {
    async session({ session, token }) {
      if (token) {
        session.gigyaProfile = token.gigyaProfile as Record<string, unknown>;
        session.cardNumber = token.cardNumber as string;
        session.gigyaToken = token.gigyaToken as string;
      }
      return session;
    },
    async jwt({ token, user }) {
      const isDuringSignin = !!user;
      
      if (isDuringSignin && user && 'gigyaProfile' in user) {
        token.gigyaProfile = (user as any).gigyaProfile;
        token.cardNumber = (user as any).cardNumber;

        // Generate SAP CDC JWT for API calls
        const gigyaService = getGigyaService();
        const uid = String(token.gigyaProfile?.uid || user.id || '');
        
        if (uid) {
          try {
            const gigyaToken = await gigyaService.getJWT(uid);
            if (gigyaToken) {
              token.gigyaToken = gigyaToken;
            }
          } catch (error) {
            console.error('Error getting SAP CDC JWT:', error);
          }
        }
      }

      return token;
    },
  },
  events: {
    async signOut({ token }) {
      console.log('User signed out:', {
        hasGigyaProfile: !!token?.gigyaProfile,
        cardNumber: token?.cardNumber,
      });
    },
  },
  debug: false,
};

export default async function auth(req: NextApiRequest, res: NextApiResponse) {
  return await NextAuth(req, res, authOptions);
}

Key Points:

• JWT verification uses SAP CDC's public key (RSA256)
• Session stores minimal data in encrypted HttpOnly cookies
• Works with Sitecore's headless architecture

Step 6: Create Login Page

Create src/pages/login.tsx:

/* eslint-disable @typescript-eslint/no-explicit-any */
import { signIn } from 'next-auth/react';
import { useCallback, useEffect, useState } from 'react';

declare global {
  interface Window {
    gigya: any;
  }
}

const GIGYA_API_KEY = process.env.NEXT_PUBLIC_GIGYA_API_KEY || '';
const GIGYA_SCREENSET = process.env.NEXT_PUBLIC_GIGYA_SCREENSET || 'Default-RegistrationLogin';
const GIGYA_START_SCREEN = process.env.NEXT_PUBLIC_GIGYA_START_SCREEN || 'gigya-login-screen';

function loadGigyaScript() {
  return new Promise<void>((resolve, reject) => {
    if ((window as any).gigya) return resolve();
    
    const script = document.createElement('script');
    const gigyaCdnBaseUrl = process.env.NEXT_PUBLIC_GIGYA_CDN_BASE_URL || 'https://cdns.us1.gigya.com';
    script.src = `${gigyaCdnBaseUrl}/js/gigya.js?apiKey=${GIGYA_API_KEY}`;
    script.async = true;
    script.onload = () => resolve();
    script.onerror = () => reject(new Error('Failed to load SAP CDC SDK'));
    document.body.appendChild(script);
  });
}

function verifyGigyaSession(): Promise<boolean> {
  return new Promise((resolve) => {
    const w = window as any;
    if (!w.gigya?.accounts?.getAccountInfo) return resolve(false);
    
    w.gigya.accounts.getAccountInfo({
      callback: (res: any) => resolve(res.errorCode === 0),
    });
  });
}

export default function LoginPage() {
  const [sdkReady, setSdkReady] = useState(false);
  const [error, setError] = useState('');

  const callbackUrl = 
    typeof window !== 'undefined'
      ? new URLSearchParams(window.location.search).get('callbackUrl')
      : null;

  const establishAppSession = useCallback(async (idToken: string) => {
    try {
      const result = await signIn('gigya', {
        id_token: idToken,
        redirect: false,
      });

      return result?.ok ? { ok: true } : { ok: false, error: result?.error };
    } catch (err: any) {
      return { ok: false, error: err.message };
    }
  }, []);

  const handleOnLogin = useCallback(() => {
    const w = window as any;

    w.gigya.accounts.getJWT({
      fields: 'profile,email,emails,data',
      expiration: 600,
      callback: async (jwtRes: any) => {
        if (jwtRes.errorCode === 0 && jwtRes.id_token) {
          const result = await establishAppSession(jwtRes.id_token);
          
          if (result.ok) {
            window.location.href = callbackUrl || '/my-account';  // Adjust redirect URL
          } else {
            setError('Session establishment failed: ' + (result.error || 'Unknown error'));
          }
        } else {
          setError('JWT generation failed: ' + (jwtRes?.errorMessage || jwtRes?.errorCode));
        }
      },
    });
  }, [establishAppSession, callbackUrl]);

  const showScreenSet = useCallback(() => {
    const w = window as any;
    if (!w.gigya?.accounts?.showScreenSet) return;

    w.gigya.accounts.addEventHandlers({
      onLogin: handleOnLogin,
    });

    w.gigya.accounts.showScreenSet({
      screenSet: GIGYA_SCREENSET,
      startScreen: GIGYA_START_SCREEN,
      onError: (e: any) => setError('Screen-Set error: ' + (e?.errorMessage || e?.errorCode)),
    });
  }, [handleOnLogin]);

  useEffect(() => {
    let mounted = true;

    loadGigyaScript()
      .then(async () => {
        if (!mounted) return;
        setSdkReady(true);

        const hasSession = await verifyGigyaSession();

        if (hasSession) {
          const w = window as any;
          w.gigya?.accounts?.getJWT({
            fields: 'profile,email,emails,data',
            expiration: 600,
            callback: async (jwtRes: any) => {
              if (jwtRes.errorCode === 0 && jwtRes.id_token) {
                const result = await establishAppSession(jwtRes.id_token);
                if (result.ok) {
                  window.location.href = callbackUrl || '/my-account';
                }
              }
            },
          });
          return;
        }

        showScreenSet();
      })
      .catch((e) => mounted && setError(String(e?.message || e)));

    return () => {
      mounted = false;
    };
  }, [establishAppSession, callbackUrl, showScreenSet]);

  return (
    <div>
      <h1>Sign In</h1>
      
      {!sdkReady && <div>Loading...</div>}
      
      {error && <div>{error}</div>}
    </div>
  );
}

export async function getServerSideProps() {
  return { props: {} };
}

Sitecore Note: The screen-set displays your branded UI - customize it in SAP CDC Console to match your Sitecore site design.

Step 7: Load SAP CDC SDK Globally

Update your src/Layout.tsx or src/pages/_app.tsx:

import Script from 'next/script';

// In your Layout component
<Script
  src={`${
    process.env.NEXT_PUBLIC_GIGYA_CDN_BASE_URL || ''
  }/js/gigya.js?apiKey=${process.env.NEXT_PUBLIC_GIGYA_API_KEY}`}
  strategy="afterInteractive"
/>

This loads the SAP CDC SDK globally for SSO and persistent sessions across your Sitecore site.

Step 8: Add Session Timeout

Create src/components/SessionTimeoutChecker.tsx:

import { useSession, signOut } from 'next-auth/react';
import { useEffect } from 'react';
import { logoutFromGigya } from '@/lib/gigya/gigya-service';

export function SessionTimeoutChecker() {
  const { data: session, status } = useSession();

  useEffect(() => {
    if (status !== 'authenticated' || !session) return;

    const timeoutMinutes = Number(process.env.NEXT_PUBLIC_SESSION_TIMEOUT_MINUTES) || 30;
    const timeoutMs = timeoutMinutes * 60 * 1000;

    let lastActivity = Date.now();
    const resetActivity = () => (lastActivity = Date.now());

    const events = ['mousedown', 'keydown', 'scroll', 'touchstart'];
    events.forEach((event) => window.addEventListener(event, resetActivity));

    const interval = setInterval(async () => {
      if (Date.now() - lastActivity >= timeoutMs) {
        await logoutFromGigya();
        await signOut({ callbackUrl: '/login?reason=timeout', redirect: false });
        window.location.href = '/login?reason=timeout';
      }
    }, 60 * 1000);

    return () => {
      events.forEach((event) => window.removeEventListener(event, resetActivity));
      clearInterval(interval);
    };
  }, [session, status]);

  return null;
}

Add to your _app.tsx:

import { SessionProvider } from 'next-auth/react';
import { SessionTimeoutChecker } from '@/components/SessionTimeoutChecker';

function MyApp({ Component, pageProps: { session, ...pageProps } }) {
  return (
    <SessionProvider session={session}>
      <SessionTimeoutChecker />
      <Component {...pageProps} />
    </SessionProvider>
  );
}

Step 9: Add Logout

In your Sitecore header component:

import { signOut } from 'next-auth/react';
import { logoutFromGigya } from '@/lib/gigya/gigya-service';

export function LogoutButton() {
  const handleSignOut = async () => {
    await logoutFromGigya();  // Clear SAP CDC session first
    await signOut({ callbackUrl: '/login', redirect: false });
    window.location.href = '/login';
  };

  return <button onClick={handleSignOut}>Sign Out</button>;
}

Step 10: Protect Sitecore Routes

Create src/middleware.ts:

import { getToken } from 'next-auth/jwt';
import { NextRequest, NextResponse } from 'next/server';

export async function middleware(req: NextRequest) {
  const pathname = req.nextUrl.pathname;

  // Define protected Sitecore routes
  const protectedRoutes = ['/my-account', '/profile', '/settings'];

  const isProtectedRoute = protectedRoutes.some(route => pathname.startsWith(route));

  if (isProtectedRoute) {
    const token = await getToken({
      req,
      secret: process.env.NEXTAUTH_SECRET,
    });

    if (!token) {
      const url = req.nextUrl.clone();
      url.pathname = '/login';
      url.searchParams.set('callbackUrl', pathname);
      return NextResponse.redirect(url);
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/((?!api/|_next/|favicon.ico|public/).*)',],
};

Using in Your Sitecore Components

Client-Side (React Components)

import { useSession } from 'next-auth/react';

export function MyAccountComponent() {
  const { data: session, status } = useSession();

  if (status === 'loading') return <div>Loading...</div>;
  if (status === 'unauthenticated') return <div>Please sign in</div>;

  return (
    <div>
      <h1>Welcome, {session?.user?.name}</h1>
      <p>User ID: {session?.cardNumber}</p>
      <p>Email: {session?.user?.email}</p>
    </div>
  );
}

Server-Side (Sitecore API Routes)

import { getServerSession } from 'next-auth/next';
import { authOptions } from './auth/[...nextauth]';
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const session = await getServerSession(req, res, authOptions);

  if (!session) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Use session.gigyaToken for SAP CDC API calls
  // Use session.cardNumber for Sitecore personalization

  return res.status(200).json({ message: 'Protected data', user: session.user });
}

Sitecore Page Props

import { getServerSession } from 'next-auth/next';
import { authOptions } from './api/auth/[...nextauth]';

export async function getServerSideProps(context) {
  const session = await getServerSession(context.req, context.res, authOptions);

  if (!session) {
    return {
      redirect: { destination: '/login', permanent: false },
    };
  }

  return {
    props: {
      session,
      // Pass to Sitecore components
    },
  };
}

Common Issues and Fixes

"Failed to load SAP CDC SDK"

• Cause: Incorrect CDN URL or API key
• Fix: Check NEXT_PUBLIC_GIGYA_CDN_BASE_URL matches your data center (us1/eu1/au1)
• Fix: Verify API key is correct in SAP CDC Console

"JWT verification failed"

• Cause: Public key fetch failure or token expiration
• Fix: Ensure NEXT_PUBLIC_GIGYA_API_KEY is correct
• Fix: Verify data center URLs match your SAP CDC account region
• Fix: Check token hasn't expired (default: 10 minutes)

"Session not persisting"

• Cause: NEXTAUTH_URL mismatch or missing secret
• Fix: Verify NEXTAUTH_URL matches your domain exactly
• Fix: Ensure NEXTAUTH_SECRET is set and consistent across instances
• Fix: Check browser cookies are enabled

"Screen-set not displaying"

• Cause: SDK not loaded or incorrect screen-set name
• Fix: Confirm screen-set name in SAP CDC Console matches NEXT_PUBLIC_GIGYA_SCREENSET
• Fix: Check browser console for JavaScript errors
• Fix: Verify SDK loaded before calling showScreenSet()

"Race condition: gigya is not defined"

• Cause: Using SDK before it's loaded
• Fix: Always use loadGigyaScript() Promise before accessing window.gigya
• Fix: Check SDK loading status before making API calls

Security Best Practices

Essential Security Checklist

✅ Environment Variables

• Add .env.local to .gitignore
• Use different secrets for dev/staging/production
• Store production secrets in hosting platform (Vercel, Azure, etc.)

✅ JWT Security

• Tokens stored in HttpOnly cookies (XSS protection)
• Short expiration times (30 minutes recommended)
• Always verify tokens server-side

✅ Session Management

• Implement session timeout (default: 30 minutes)
• Clear both SAP CDC and NextAuth sessions on logout
• Validate sessions on every protected request

✅ API Security

// Always verify session server-side
const session = await getServerSession(req, res, authOptions);
if (!session) return res.status(401).json({ error: 'Unauthorized' });

✅ CORS Configuration

• Whitelist your domains in SAP CDC Console → Security → Trusted Sites
• Never use wildcard (*) in production

✅ HTTPS

• Always use HTTPS in production
• Secure cookies require HTTPS

Production Deployment

Sitecore XM Cloud Deployment

1. Add environment variables in XM Cloud portal or CI/CD pipeline
2. Configure SAP CDC trusted sites with production URLs
3. Update NEXTAUTH_URL to production domain
4. Test authentication thoroughly before going live
5. Enable HTTPS and secure cookies
6. Monitor authentication logs and errors

Vercel Deployment

vercel env add NEXTAUTH_SECRET production
vercel env add GIGYA_USER_KEY production
vercel env add GIGYA_SECRET production
# Add all other secrets

Resources

• SAP CDC Documentation: help.sap.com/docs/SAP_CUSTOMER_DATA_CLOUD
• NextAuth.js: next-auth.js.org
• Sitecore JSS: doc.sitecore.com/xmc/en/developers/jss
• Sitecore XM Cloud: doc.sitecore.com/xmc

Conclusion

Implementing SAP Customer Data Cloud authentication in Sitecore XM Cloud Next.js applications requires careful attention to JWT verification, session management, and SDK initialization. The challenges we faced—from dynamic public key fetching to session synchronization—are common in enterprise authentication implementations.

By following this guide and addressing the challenges we documented, you can build a production-ready authentication system that:

✅ Securely authenticates users with JWT-based tokens
✅ Integrates with Sitecore's headless architecture
✅ Maintains session state across page reloads and navigation
✅ Protects routes with middleware-based authentication
✅ Provides foundation for personalization with Sitecore Personalize

Remember: Always follow security best practices, keep dependencies updated, and test thoroughly in staging before production deployment. The authentication layer is critical—take time to get it right.

Happy coding! 🚀

To solve this, I built a Marketplace app that plugs directly into XM Cloud and lets you run a quick audit on published pages. The results show up instantly inside the Pages editor.

The Idea Behind the App

The idea was simple. Instead of relying on external tools or waiting for SEO audits later, authors can now check their published pages right inside XM Cloud.

It makes the process faster, removes context switching, and gives immediate insights into metadata and accessibility.

How the App Works

The app is built with Next.js and TypeScript and embedded into Sitecore Pages via the Marketplace. When opened, it fetches the published page’s rendered HTML and checks for:

• Missing alt attributes on images
• Missing or duplicate meta titles and descriptions
• Incorrect heading structure

The results are displayed in a clean panel inside Pages.

Creating and Configuring the App in Sitecore XM Cloud

Here’s the exact process I followed to create and configure the app:

1. Build the app locally

git clone https://github.com/mgnventures/xmc-page-seo-audit-app.git
cd xmc-page-seo-audit-app
npm install
npm run dev

The app runs on http://localhost:3000.

2. Deploy the app
   Push it to Vercel, Netlify, or Azure.

3. Register the app in Sitecore XM Cloud

• Go to Sitecore Cloud Portal.
• Navigate to Cloud Portal → Developer Studio → Create App.

• Fill in details:

  • Name
  • App icon (from your repo’s public folder)
  • App URL (your deployed endpoint)
  • Select Pages Context Panel as the extension point

  

  

• Save the configuration.

4. Install the app in XM Cloud

• Open Sitecore Prtal.
• Go to the My Apps tab.
• Search for your app and click Install.

• The app now appears as a panel inside Pages.

Real Use Cases

• A content author can check if their published landing page has proper alt text.
• A marketer can confirm that the page has a correct title and description.
• A developer can extend the app with custom rules for their project.

The biggest win is that you can run these checks on the live published page and see results immediately in XM Cloud.

Getting Started Guide

For anyone who wants to try this app:

git clone https://github.com/mgnventures/xmc-page-seo-audit-app.git

Then follow the steps above to register and configure the app in XM Cloud.

Reflections and Future Potential

Building this app showed me how easy it is to extend XM Cloud with custom utilities. The Marketplace is still new, and even small apps like this can add real value for authors and marketers.

Next, I would like to refine the audit rules and improve how results are displayed. I also hope other developers fork the project on GitHub and help make it more stable and useful:

👉 GitHub Repo – xmc-page-seo-audit-app

In the end, this app is about more than code—it’s about contributing something practical to the Sitecore community.

This post walks through implementing a Secured Pages SXA Module using Next.js middleware architecture, similar to Sitecore's out-of-the-box redirect module. The solution provides a flexible, configuration-driven approach to protect pages based on path patterns stored in Sitecore.

The Challenge

In headless Sitecore implementations, traditional server-side authentication checks aren't always feasible. You need:

• Flexible path matching: Support for both exact paths (/Profile) and regex patterns (/securedTree*)
• Sitecore-driven configuration: Content authors should be able to configure secured paths without code deployments
• Middleware-based protection: Leverage Next.js middleware for efficient request interception
• GraphQL integration: Fetch security mappings from Sitecore's GraphQL endpoint
• Performance: Cache security mappings to avoid repeated API calls

Solution Overview

The Secured Pages SXA Module consists of three main components:

1. SecuredPagesMiddleware: Next.js middleware that intercepts requests and checks authentication
2. GraphQLSecuredPagesService: Service that fetches security mappings from Sitecore via GraphQL
3. Sitecore Content Structure: Templates and items that store the security configuration

Architecture Flow

Request → Middleware → Check Authentication Token
                          ↓
                    Is Authorized?
                    /           \
                  Yes            No
                   ↓              ↓
            Allow Request    Check Sitecore Mappings
                                  ↓
                          Path Matches Secured Pattern?
                          /                    \
                        Yes                     No
                         ↓                       ↓
                  Redirect to Login        Allow Request

Sitecore Setup

Step 1: Create the Secured Pages Template

First, create a template in Sitecore to store security mappings:

1. Navigate to /sitecore/templates/Project/YourProject/Security

2. Create a new template named Secured Pages

3. Add the following fields:

   • UrlMapping (Multi-Line Text)

     • Description: "Enter relative paths or regex patterns (one per line). Examples: /Profile, /securedTree*"

   • LoginRedirectUrl (Single-Line Text)

     • Description: "Relative URL to redirect unauthorized users (e.g., /login)"

4. Set the template ID and note it for use in your constants file:

// lib/constants.ts
export const securedPagesTemplateId = '{YOUR-TEMPLATE-ID-HERE}';

Step 2: Create Security Mappings Container

1. Navigate to your site's root item (e.g., /sitecore/content/YourSite)
2. Create a folder named Settings (if it doesn't exist)
3. Under Settings, create a folder named Security Mappings
4. Set insert options on Security Mappings to allow Secured Pages template

Step 3: Create Security Mapping Items

For each set of secured paths:

1. Navigate to Settings/Security Mappings
2. Insert → Secured Pages
3. Configure:
   • UrlMapping: Enter paths (one per line):

     /Profile
     /Account/*
     /Admin/.*
     

   • LoginRedirectUrl: /login

Code Implementation

Step 1: Create Constants File

// lib/constants.ts
export const securedPagesTemplateId = '{YOUR-TEMPLATE-ID-HERE}';

Step 2: GraphQL Service Implementation

The GraphQLSecuredPagesService fetches security mappings from Sitecore:

// lib/middleware/graphql-auth-service.ts
import {
  GraphQLRequestClient,
  GraphQLRequestClientFactory,
} from '@sitecore-jss/sitecore-jss-nextjs/graphql';
import { securedPagesTemplateId } from '../constants';

export const GetItemUrl = /* GraphQL */ `
  query GetItemIdByPath($path: String, $lang: String = "en") {
    item(path: $path, language: $lang) {
      id
    }
  }
`;

const SiteRootQuery = /* GraphQL */ `
  query SiteRootQuery($siteName: String!) {
    site {
      siteInfo(site: $siteName) {
        rootPath
      }
    }
  }
`;

const defaultQuery = /* GraphQL */ `
  query SearchSecuredPages($pathId: String!, $templateId: String!) {
    search(
      where: {
        AND: [
          { name: "_path", value: $pathId, operator: CONTAINS }
          { name: "_templates", value: $templateId, operator: CONTAINS }
        ]
      }
      first: 1
    ) {
      total
      pageInfo {
        endCursor
        hasNext
      }
      results {
        UrlMapping: field(name: "UrlMapping") {
          value
        }
        LoginRedirectUrl: field(name: "LoginRedirectUrl") {
          value
        }
      }
    }
  }
`;

export type GraphQLSecuredPagesServiceConfig = {
  endpoint?: string;
  apiKey?: string;
  fetch?: typeof fetch;
  clientFactory?: GraphQLRequestClientFactory;
  cacheEnabled?: boolean;
  cacheTimeout?: number;
};

export type SecuredPagesQueryResult = {
  search: {
    total: number;
    results: resultEntry[] | null;
  };
};

export type resultEntry = {
  UrlMapping: resultField;
  LoginRedirectUrl: resultField;
};

export type resultField = {
  value: string;
};

type SiteRootQueryResult = {
  site: { siteInfo: { rootPath: string } | null };
};

type TItem = {
  id: string;
};

type TGetItemId = {
  item: TItem;
};

export class GraphQLSecuredPagesService {
  private graphQLClient: GraphQLRequestClient;
  private cache: Map<string, { value: SecuredPagesQueryResult; expiresAt: number }> = new Map();

  protected get siteRootQuery(): string {
    return SiteRootQuery;
  }

  protected get query(): string {
    return defaultQuery;
  }

  constructor(private options: GraphQLSecuredPagesServiceConfig) {
    this.graphQLClient = this.getGraphQLClient();
  }

  async fetchSecuredPages({ siteName }: { siteName: string }): Promise<SecuredPagesQueryResult> {
    if (!siteName) {
      throw new Error('The siteName cannot be empty');
    }

    // Check cache first
    const cacheKey = `auth-${siteName}`;
    const cached = this.cache.get(cacheKey);
    
    if (cached && Date.now() < cached.expiresAt) {
      return cached.value;
    }

    // Fetch from Sitecore
    const siteRoot = await this.graphQLClient.request<SiteRootQueryResult>(this.siteRootQuery, {
      siteName,
    });
    
    if (!siteRoot?.site?.siteInfo?.rootPath) {
      return { search: { total: 0, results: [] } };
    }

    const settingItemPath = siteRoot.site.siteInfo.rootPath + '/Settings';
    const settingItemData = await this.graphQLClient.request<TGetItemId>(GetItemUrl, {
      path: settingItemPath,
    });
    
    if (!settingItemData?.item?.id) {
      return { search: { total: 0, results: [] } };
    }

    const pathId = settingItemData.item.id;
    const securedPages = await this.graphQLClient.request<SecuredPagesQueryResult>(
      this.query,
      {
        pathId,
        templateId: securedPagesTemplateId,
      }
    );
    
    // Cache the result
    if (securedPages) {
      const cacheTimeout = (this.options.cacheTimeout || 10) * 1000;
      this.cache.set(cacheKey, {
        value: securedPages,
        expiresAt: Date.now() + cacheTimeout,
      });
      return securedPages;
    }
    
    return { search: { total: 0, results: [] } };
  }

  protected getGraphQLClient(): GraphQLRequestClient {
    if (!this.options.endpoint) {
      if (!this.options.clientFactory) {
        throw new Error('You should provide either an endpoint and apiKey, or a clientFactory.');
      }

      return this.options.clientFactory({
        fetch: this.options.fetch,
      });
    }

    return new GraphQLRequestClient(this.options.endpoint, {
      apiKey: this.options.apiKey,
      fetch: this.options.fetch,
    });
  }
}

Key Features:

• Caching: Uses in-memory cache to avoid repeated GraphQL calls (default: 10 seconds)
• Path Resolution: Dynamically resolves the site's Settings folder path
• Template Filtering: Searches for items using the Secured Pages template ID

Note: The caching implementation uses a simple in-memory Map. For production environments with multiple instances, consider implementing a distributed cache solution.

Step 3: Middleware Implementation

The middleware intercepts requests and enforces authentication:

// lib/middleware/secured-pages-middleware.ts
import { SiteInfo } from '@sitecore-jss/sitecore-jss-nextjs';
import { MiddlewareBase, MiddlewareBaseConfig } from '@sitecore-jss/sitecore-jss-nextjs/middleware';
import { getToken } from 'next-auth/jwt';
import { NextRequest, NextResponse } from 'next/server';
import regexParser from 'regex-parser';
import {
  GraphQLSecuredPagesService,
  GraphQLSecuredPagesServiceConfig,
  resultEntry,
} from './graphql-auth-service';

export type SecuredPagesMiddlewareConfig = Omit<GraphQLSecuredPagesServiceConfig, 'fetch'> &
  MiddlewareBaseConfig & {
    protectedRoutes?: string[];
    defaultLoginPage?: string;
    locales: string[];
  };

export class SecuredPagesMiddleware extends MiddlewareBase {
  private securedPagesService: GraphQLSecuredPagesService;

  constructor(protected config: SecuredPagesMiddlewareConfig) {
    super(config);
    this.securedPagesService = new GraphQLSecuredPagesService({ ...config, fetch: fetch });
  }

  public getHandler(): (req: NextRequest, res?: NextResponse) => Promise<NextResponse> {
    return async (req, res) => {
      return await this.handler(req, res);
    };
  }

  private handler = async (req: NextRequest, res?: NextResponse): Promise<NextResponse> => {
    // Skip if disabled or in preview mode
    if (
      (this.config.disabled && this.config.disabled(req, res || NextResponse.next())) ||
      this.isPreview(req) ||
      this.excludeRoute(req.nextUrl.pathname)
    ) {
      return res || NextResponse.next();
    }

    const site = this.getSite(req, res);
    const isSecured = this.config.protectedRoutes?.includes(req.nextUrl.pathname);
    const existsSecuredPageMapping = await this.getExistsSecuredPages(req, site.name);

    // Allow if not secured
    if (!isSecured && !existsSecuredPageMapping) {
      return res || NextResponse.next();
    }

    // Check authorization
    if (await this.isAuthorized(req)) {
      return res || NextResponse.next();
    }

    // Redirect to login
    const url = req.nextUrl.clone();
    url.pathname =
      existsSecuredPageMapping?.LoginRedirectUrl?.value || this.config.defaultLoginPage || '/';
    url.locale = req.nextUrl.locale;

    return NextResponse.redirect(decodeURIComponent(url.href));
  };

  private async isAuthorized(req: NextRequest): Promise<boolean> {
    const secret = process.env.NEXTAUTH_JWT_SECRET;
    const token = await getToken({ req, secret });
    return !!token;
  }

  private async getExistsSecuredPages(
    req: NextRequest,
    siteName: string
  ): Promise<resultEntry | undefined> {
    const securedPages = await this.securedPagesService.fetchSecuredPages({ siteName });

    if (!securedPages?.search?.results || securedPages.search.total === 0) {
      return undefined;
    }

    const pathname = req.nextUrl.pathname.toLowerCase();
    const pathnameWithLocale = `/${req.nextUrl.locale}${req.nextUrl.pathname}`.toLowerCase();

    // Check each secured page mapping
    for (const result of securedPages.search.results) {
      const urlMappings = result?.UrlMapping?.value;
      if (!urlMappings) continue;

      const paths = urlMappings.split(/\r?\n/);
      
      for (const urlMapping of paths) {
        if (!urlMapping.trim()) continue;

        const pattern = regexParser(urlMapping.toLowerCase());
        const matches = pattern.test(pathname) || pattern.test(pathnameWithLocale);

        if (matches && result.LoginRedirectUrl) {
          return result;
        }
      }
    }

    return undefined;
  }
}

Key Features:

• Token Verification: Uses next-auth/jwt to verify authentication tokens
• Path Matching: Supports both exact paths and regex patterns
• Locale Awareness: Matches paths with and without locale prefixes
• Preview Mode: Skips authentication checks in Sitecore preview mode
• Configurable Routes: Supports both Sitecore-driven and code-based protected routes

Configuration

Environment Variables

Add to your .env file:

# Enable/disable the secured pages module
Enable_Auth_Secured_Pages=true

# NextAuth JWT secret (required for token verification)
NEXTAUTH_JWT_SECRET=your-secret-key-here

Middleware Integration

Integrate the middleware in your Next.js middleware file:

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { createGraphQLClientFactory } from '@sitecore-jss/sitecore-jss-nextjs';
import { SecuredPagesMiddleware } from './lib/middleware/secured-pages-middleware';

const securedPagesMiddleware = new SecuredPagesMiddleware({
  // GraphQL configuration
  clientFactory: createGraphQLClientFactory({
    endpoint: process.env.GRAPH_QL_ENDPOINT!,
    apiKey: process.env.SITECORE_API_KEY!,
  }),

  // Middleware configuration
  defaultHostname: process.env.SITECORE_DEFAULT_HOSTNAME || 'localhost',
  locales: ['en', 'es', 'fr'], // Add your locales
  defaultLoginPage: '/login',
  
  // Optional: Code-based protected routes (in addition to Sitecore config)
  protectedRoutes: ['/admin', '/dashboard'],
  
  // Cache configuration
  cacheEnabled: true,
  cacheTimeout: 10, // seconds

  // Exclude routes from authentication checks
  excludeRoute: (pathname: string) => {
    return pathname.startsWith('/api') || pathname.startsWith('/_next');
  },

  // Disable middleware conditionally
  disabled: (req: NextRequest) => {
    return process.env.Enable_Auth_Secured_Pages !== 'true';
  },
});

export async function middleware(req: NextRequest) {
  // Run other middlewares first (e.g., Sitecore JSS middleware)
  // Then run secured pages middleware
  return securedPagesMiddleware.getHandler()(req);
}

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico).*)',
  ],
};

Step-by-Step Setup Guide

1. Install Dependencies

npm install regex-parser next-auth

2. Create File Structure

lib/
  ├── constants.ts
  └── middleware/
      ├── secured-pages-middleware.ts
      └── graphql-auth-service.ts

3. Configure Sitecore

1. Create the Secured Pages template with UrlMapping and LoginRedirectUrl fields
2. Create Settings/Security Mappings folder under your site root
3. Create security mapping items as needed

4. Update Environment Variables

Add Enable_Auth_Secured_Pages and NEXTAUTH_JWT_SECRET to your .env file.

5. Integrate Middleware

Add the middleware configuration to middleware.ts as shown above.

6. Test the Implementation

1. Test Unauthorized Access: Visit a secured path without authentication → should redirect to login
2. Test Authorized Access: Login and visit secured path → should allow access
3. Test Regex Patterns: Verify that patterns like /securedTree* match correctly

Advanced Configuration

Multiple Security Mappings

You can create multiple Secured Pages items under Security Mappings, each with different path patterns and redirect URLs. The middleware will check all mappings and use the first match.

Combining Code-Based and Sitecore-Based Routes

The middleware supports both approaches:

• Code-based: Define protectedRoutes in middleware config
• Sitecore-based: Configure paths in Sitecore items

Both are checked, and either can trigger authentication.

Custom Authentication Logic

To use a different authentication provider, modify the isAuthorized method:

private async isAuthorized(req: NextRequest): Promise<boolean> {
  // Example: Check custom session cookie
  const sessionCookie = req.cookies.get('session');
  return !!sessionCookie?.value;
  
  // Or: Check custom header
  const authHeader = req.headers.get('Authorization');
  return authHeader?.startsWith('Bearer ') ?? false;
}

Performance Considerations

• Caching: Security mappings are cached for 10 seconds by default. Adjust cacheTimeout based on your needs.
• GraphQL Efficiency: The service uses a single GraphQL query to fetch all mappings for a site.
• Middleware Overhead: Middleware runs on every request. Use excludeRoute to skip static assets and API routes.

Troubleshooting

Mappings Not Found

• Verify the template ID in constants.ts matches your Sitecore template
• Check that items exist under Settings/Security Mappings
• Ensure the UrlMapping field is populated

Redirects Not Working

• Verify LoginRedirectUrl is set in Sitecore items
• Check that defaultLoginPage is configured in middleware
• Ensure the login page route exists

Authentication Not Detected

• Verify NEXTAUTH_JWT_SECRET is set correctly
• Check that your authentication provider sets tokens correctly

Final Thoughts

The Secured Pages SXA Module provides a flexible, maintainable solution for protecting pages in headless Sitecore implementations. By leveraging Next.js middleware and Sitecore's content management capabilities, you can:

• Empower content authors to configure security without code changes
• Maintain performance through intelligent caching
• Support complex scenarios with regex pattern matching
• Integrate seamlessly with existing authentication providers

This approach follows Sitecore best practices by keeping configuration in the CMS while leveraging Next.js's powerful middleware capabilities for request handling.

Ready to secure your headless site?
👉 Follow the step-by-step guide above to implement the module in your Next.js Sitecore project.

This guide provides enterprise-grade optimization patterns based on real production implementations. You'll learn concrete techniques to reduce query complexity, eliminate N+1 problems, and leverage Experience Edge caching effectively.

⚠️ The Problem: What's Killing Your GraphQL Performance

Common Issues

Over-fetching: Requesting more fields than needed, increasing payload size and processing time.

N+1 Query Problem: Making sequential queries instead of batching, multiplying API calls.

Complex Nested Queries: Deeply nested field resolution triggering expensive data lookups.

Cache Misses: Not leveraging Experience Edge caching, causing repeated expensive queries.

Inefficient Fragments: Not reusing query fragments, duplicating field definitions.

Real-World Impact

• Page load time: 2-5 seconds (should be less than 500ms)
• API latency: 500ms-2s per request (should be less than 100ms)
• Network bandwidth: 2-5MB per page load (should be less than 200KB)
• Experience Edge cache hit rate: 30-40% (should be greater than 90%)

🧩 Solution 1: GraphQL Fragments for Reusability

Use fragments to define reusable field sets and avoid duplication.

fragment ComponentFieldsFragment on Component {
  id
  name
  displayName
  fields {
    name
    value
  }
}

query GetPages {
  search(where: { AND: [{ name: "_templatename", value: "Page" }] }) {
    results {
      ...ComponentFieldsFragment
      children {
        ...ComponentFieldsFragment
      }
    }
  }
}

Benefits:

• Reduced query size by 30-40%
• Easier to maintain field lists across queries
• Better cache utilization

🔄 Solution 2: Batching with Aliases

Instead of multiple sequential queries, use aliases to batch requests into a single GraphQL call.

query BatchedQuery {
  header: item(path: "/sitecore/content/home/header") {
    id
    name
  }
  footer: item(path: "/sitecore/content/home/footer") {
    id
    name
  }
  navigation: item(path: "/sitecore/content/home/navigation") {
    id
    name
  }
}

Impact:

• Reduces API calls from 3 to 1
• Single network round-trip vs. three
• Faster overall page rendering

📄 Solution 3: Cursor-Based Pagination

Avoid loading all items at once. Use cursor-based pagination for large datasets.

query PaginatedSearch($first: Int!, $after: String) {
  search(
    where: { AND: [{ name: "_templatename", value: "BlogPost" }] }
    first: $first
    after: $after
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    results {
      id
      name
      url
      createdDate
    }
  }
}

Variables:

{
  "first": 20,
  "after": null
}

Benefits:

• Load only what's needed
• Faster initial page loads
• Better memory usage

💾 Solution 4: Experience Edge Cache Configuration

Experience Edge caches layout data automatically, but only if you configure it correctly.

// next.config.js
module.exports = {
  revalidate: 60, // ISR: revalidate every 60 seconds
  headers: async () => {
    return [
      {
        source: '/api/graphql',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, s-maxage=300, stale-while-revalidate=600'
          }
        ]
      }
    ];
  }
};

Cache Hierarchy:

1. CDN cache (Experience Edge) - 5 minutes
2. Browser cache - 10 minutes
3. Application cache - In-memory storage

🧮 Solution 5: Query Complexity Analysis

Implement query complexity scoring to reject expensive queries before execution.

// Apollo Server with complexity plugin
import { createComplexityLimitPlugin } from 'graphql-query-complexity';

const server = new ApolloServer({
  schema,
  plugins: [
    createComplexityLimitPlugin({
      maxComplexity: 1000,
      onComplete: (complexity) => {
        console.log(`Query complexity: ${complexity}`);
      }
    })
  ]
});

Complexity Scoring Guide:

• Simple field: 1 point
• Relational field: 5 points
• Collection: 10 points per item
• Nested relations: Multiplicative

⚡ Solution 6: DataLoader for Batch Processing

Prevent N+1 problems by batching database lookups automatically.

import DataLoader from 'dataloader';

const componentLoader = new DataLoader(async (componentIds) => {
  return await Promise.all(
    componentIds.map(id => getComponentFromCache(id))
  );
});

// In resolver
const resolveComponent = async (parent, args) => {
  return componentLoader.load(args.componentId);
};

Benefits:

• Automatically batches queries
• Single DB round-trip for multiple items
• Reduces latency by 50-70%

✅ Performance Checklist

• Use GraphQL fragments for all field sets
• Batch queries with aliases where possible
• Implement cursor-based pagination for collections
• Configure ISR revalidation times appropriately
• Set correct Cache-Control headers
• Monitor query complexity
• Use DataLoader in resolvers
• Profile queries in production
• Set up alerts for slow queries (greater than 500ms)
• Review Experience Edge cache hit rates monthly

📊 Monitoring and Measurement

Track these metrics to measure optimization impact:

Query Performance:

• Average query time (target: less than 100ms)
• P95 query time (target: less than 500ms)
• Queries per second (baseline)

Cache Effectiveness:

• Experience Edge hit rate (target: greater than 90%)
• Cache size (monitor for bloat)
• Stale content incidents

Business Impact:

• Page load time
• Core Web Vitals (LCP, FID, CLS)
• Bounce rate

🛠️ Tools for Analysis

Apollo DevTools: Browser extension showing query execution details

GraphQL Analyzer: Query complexity and performance scoring

Experience Edge Insights: Built-in Sitecore caching dashboard

Lighthouse: Core Web Vitals measurement

🎯 Conclusion

GraphQL performance optimization isn't a one-time effort—it's a continuous process. Start with query fragments and batching, then progressively implement caching and complexity controls. Monitor regularly and adjust based on production metrics.

The techniques in this guide can reduce API latency by 60-80% and improve page load times significantly. Apply them incrementally and measure the impact on your specific workload.

🧩 Prerequisites

• Windows 10/11 with Administrator rights
• Chocolatey (Windows package manager)
• Node.js LTS, Caddy, mkcert, Git, VS Code

Already have Chocolatey and some tools? Great—just skip whatever’s installed and keep moving.

📦 1. Install Chocolatey

Chocolatey makes the rest of the tooling painless.

1. Launch PowerShell as Administrator.
2. Run:

   Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
   

3. Confirm it worked:

   choco -v
   

🧱 2. Install Your Toolchain

With Chocolatey ready, pull down everything in one shot (still in elevated PowerShell):

choco install nodejs-lts mkcert caddy git vscode -y

Feel free to trim that list if you already have Git or VS Code.

🔒 3. Generate Local Certificates

Certs live alongside the project so Caddy can reference them.

cd C:\Projects\pennent-xm-cloud\gigya-local-setup
mkcert -install
mkcert localdev.corp.test

You’ll get:

• localdev.corp.test.pem
• localdev.corp.test-key.pem

Keep both inside gigya-local-setup.

🧠 4. Map the Domain in hosts

Point your custom domain at localhost (IPv4 and IPv6).

1. Open Notepad as Administrator.
2. Edit C:\Windows\System32\drivers\etc\hosts.
3. Append:

   127.0.0.1   localdev.corp.test
   ::1         localdev.corp.test
   

4. Save and flush DNS:

   ipconfig /flushdns
   

🛑 5. Free Up Ports 80/443

Caddy won’t start if IIS (or anything else) has those ports locked.

Stop-Service W3SVC -Force
Set-Service W3SVC -StartupType Manual
netstat -ano | findstr ":80 "
netstat -ano | findstr ":443 "

If something’s still listening, track the PID and stop it:

Stop-Process -Id <PID> -Force

🧾 6. Author the Caddyfile

Create a file literally named Caddyfile in C:\Projects\pennent-xm-cloud\gigya-local-setup:

localdev.corp.test:443 {
    tls localdev.corp.test.pem localdev.corp.test-key.pem
    reverse_proxy localhost:3000
}

• localhost:3000 → where your Next.js/Sitecore JSS dev server runs
• localdev.corp.test → the domain you mapped in hosts

🚀 7. Run Caddy

From the same directory:

cd C:\Projects\pennent-xm-cloud\gigya-local-setup
caddy run --config Caddyfile

Look for a log line similar to:

http.log        server running  {"name": "srv0", "protocols": ["h1", "h2", "h3"]}

That’s Caddy reverse-proxying HTTPS traffic to your dev server.

✅ 8. Test the Site

Fire up your Next.js app (npm run dev) and load https://localdev.corp.test in the browser. You should see:

• Your local Sitecore JSS experience
• A trusted certificate (padlock + “Connection is secure”)

🧹 9. Optional: Format the Caddyfile

Caddy can tidy and lint its own config:

caddy fmt --overwrite Caddyfile

🔁 10. Troubleshooting Cheat Sheet

🔄 11. After Every Reboot

1. Stop IIS (Stop-Service W3SVC -Force).
2. Start your Next.js app (npm run dev).
3. Launch Caddy (caddy run --config Caddyfile).
4. Visit https://localdev.corp.test.

Repeat whenever you restart your machine or swap branches.

🧭 Summary

Result: your Next.js + Sitecore JSS environment is available at https://localdev.corp.test with a fully trusted padlock, no surprises.

This guide covers production-grade caching patterns that deliver sub-second responses while maintaining content freshness.

⚠️ The Caching Challenge

Common Problems:

1. Stale Content: Users see outdated information after publishing
2. Cache Invalidation: Correct invalidation is harder than it seems
3. Unpredictable Performance: Sometimes fast, sometimes slow
4. High Latency Spikes: Traffic causes cache misses

Real-World Impact:

• First Contentful Paint (FCP): 3-5 seconds (should be less than 1.8s)
• Largest Contentful Paint (LCP): 5-8 seconds (should be less than 2.5s)
• Bounce rate: 30-40% (should be less than 10%)

🏗️ Caching Layers Architecture

┌────────────────────────────────────────────────────┐
│              User Browser                          │
│          (Browser Cache: 1 hour)                   │
└────────────┬─────────────────────────────────────┘
             │ Cache Miss
             ↓
┌────────────────────────────────────────────────────┐
│          CDN Edge (Akamai/Cloudflare)             │
│          (CDN Cache: 5-60 minutes)                 │
└────────────┬─────────────────────────────────────┘
             │ Cache Miss
             ↓
┌────────────────────────────────────────────────────┐
│          Experience Edge (Sitecore)               │
│          (Origin Cache: 10 minutes)               │
└────────────┬─────────────────────────────────────┘
             │ Cache Miss
             ↓
┌────────────────────────────────────────────────────┐
│          Next.js Application                       │
│          (ISR Cache + Application Logic)          │
└────────────┬─────────────────────────────────────┘
             │ Cache Miss
             ↓
┌────────────────────────────────────────────────────┐
│          Sitecore XM Cloud (GraphQL)              │
│          (Layout Service, Item Resolution)        │
└────────────────────────────────────────────────────┘

🌐 Part 1: CDN Caching Configuration

Setting Correct Cache Headers

// next.config.js
module.exports = {
  headers: async () => {
    return [
      // Static pages: Long cache
      {
        source: '/static/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, s-maxage=604800, stale-while-revalidate=1209600'
            // CDN: 7 days, Stale-while-revalidate: 14 days
          }
        ]
      },
      // Dynamic content: Short cache with revalidation
      {
        source: '/news/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'public, s-maxage=300, stale-while-revalidate=600'
            // CDN: 5 minutes, SWR: 10 minutes
          },
          {
            key: 'Vary',
            value: 'Accept-Encoding, User-Agent'
          }
        ]
      },
      // Personalized content: No cache
      {
        source: '/account/:path*',
        headers: [
          {
            key: 'Cache-Control',
            value: 'private, no-cache, no-store, must-revalidate'
          }
        ]
      }
    ];
  }
};

Cache Headers Reference

⚡ Part 2: Next.js ISR Configuration

ISR (Incremental Static Regeneration)

ISR combines static generation with dynamic updates.

// pages/blog/[slug].tsx
export default function BlogPost({ post }) {
  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
      <time>{post.publishedDate}</time>
    </article>
  );
}

export async function getStaticProps({ params }) {
  const post = await getPostFromXmCloud(params.slug);

  return {
    props: { post },
    revalidate: 60  // ISR: revalidate every 60 seconds
  };
}

export async function getStaticPaths() {
  // Generate paths for popular posts at build time
  const paths = await getPopularPosts();

  return {
    paths: paths.map(post => ({ params: { slug: post.slug } })),
    fallback: 'blocking'  // Generate unknown paths on-demand
  };
}

ISR Per Content Type

Different content types need different revalidation rates:

interface RevalidationConfig {
  contentType: string;
  revalidateSeconds: number;
  reason: string;
}

const revalidationConfig: RevalidationConfig[] = [
  {
    contentType: 'News Article',
    revalidateSeconds: 60,
    reason: 'Frequent updates, time-sensitive'
  },
  {
    contentType: 'Blog Post',
    revalidateSeconds: 300,
    reason: 'Updated occasionally'
  },
  {
    contentType: 'Product Details',
    revalidateSeconds: 1800,
    reason: 'Infrequently changed'
  },
  {
    contentType: 'Static Page',
    revalidateSeconds: 86400,
    reason: 'Annual updates'
  }
];

function getRevalidateTime(template: string): number {
  const config = revalidationConfig.find(c => c.contentType === template);
  return config?.revalidateSeconds ?? 300;
}

On-Demand Revalidation

Trigger revalidation immediately after publishing:

// pages/api/revalidate.ts
export default async function handler(req, res) {
  // Verify webhook is from Sitecore
  const signature = req.headers['x-sitecore-signature'];
  if (!verifySignature(req.body, signature)) {
    return res.status(401).json({ message: 'Unauthorized' });
  }

  const { itemId, path } = req.body;

  try {
    // Revalidate specific paths
    await res.revalidate(path);
    
    // Also revalidate related pages
    const relatedPaths = await getRelatedPages(itemId);
    for (const relatedPath of relatedPaths) {
      await res.revalidate(relatedPath);
    }

    return res.json({
      revalidated: true,
      paths: [path, ...relatedPaths]
    });
  } catch (error) {
    console.error('Revalidation failed:', error);
    return res.status(500).json({ message: 'Revalidation failed' });
  }
}

// Sitecore webhook configuration
// POST /api/revalidate
// Trigger on: Publish Complete
// Include: Item path, template name

🔍 Part 3: GraphQL Query Caching

Query-Level Cache Configuration

// Apollo Client cache configuration
import { InMemoryCache, HttpLink } from '@apollo/client';
import { useMemo } from 'react';

const createApolloClient = () => {
  return new ApolloClient({
    ssrMode: typeof window === 'undefined',
    link: new HttpLink({
      uri: '/api/graphql',
      credentials: 'same-origin',
      headers: {
        'sc-apikey': process.env.NEXT_PUBLIC_SITECORE_API_KEY
      }
    }),
    cache: new InMemoryCache({
      typePolicies: {
        Item: {
          keyFields: ['id'],
          fields: {
            // Cache this field for 10 minutes
            children: {
              merge(existing, incoming) {
                return incoming;
              },
              read(existing) {
                return existing;
              }
            }
          }
        },
        Query: {
          fields: {
            // Cache search results
            search: {
              merge(existing = {}, incoming) {
                return { ...existing, ...incoming };
              }
            }
          }
        }
      }
    })
  });
};

Query Complexity Optimization

# INEFFICIENT: Over-fetching nested data
query GetPageWithAllData {
  item(path: "/home") {
    id
    name
    fields {
      name
      value
    }
    children {
      id
      name
      children {
        id
        name
        children {  # Too deep!
          id
          name
        }
      }
    }
  }
}

# EFFICIENT: Fetch only needed data
query GetPageWithOptimizedFields {
  item(path: "/home") {
    id
    name
    title: field(name: "Title") {
      value
    }
    description: field(name: "Description") {
      value
    }
  }
}

# EFFICIENT: Separate queries for different concerns
fragment PageFields on Item {
  id
  name
  title: field(name: "Title") { value }
}

fragment ChildrenSummary on Item {
  id
  name
  url
}

query GetPage {
  item(path: "/home") {
    ...PageFields
    children(first: 10) {
      ...ChildrenSummary
    }
  }
}

🔄 Part 4: Cache Invalidation Patterns

Pattern 1: Time-Based Invalidation

// Simple: Set TTL and let cache expire
const config = {
  news: { ttl: 5 * 60 },        // 5 minutes
  blog: { ttl: 30 * 60 },       // 30 minutes
  product: { ttl: 2 * 60 * 60 } // 2 hours
};

Pattern 2: Event-Based Invalidation

// Listen to XM Cloud publish events
app.post('/webhooks/item-published', async (req, res) => {
  const { itemId, language, version } = req.body;

  // 1. Get item details
  const item = await xmCloud.getItem(itemId, language);

  // 2. Determine affected URLs
  const urls = await getUrlsForItem(item);

  // 3. Invalidate caches
  for (const url of urls) {
    // Invalidate CDN
    await cdn.purge(url);
    
    // Trigger ISR
    await fetch(`${process.env.SITE_URL}/api/revalidate`, {
      method: 'POST',
      body: JSON.stringify({ path: url, itemId })
    });

    // Invalidate Apollo cache
    await invalidateApolloCache(itemId);
  }

  res.status(200).json({ invalidated: urls.length });
});

Pattern 3: Smart Cache Busting

// Include version hash in URLs
const getAssetUrl = (path: string, version: string) => {
  return `${path}?v=${version}`;
};

// Sitecore item hash
const itemHash = createHash('sha256')
  .update(JSON.stringify(item))
  .digest('hex')
  .substring(0, 8);

// URLs include hash
const urls = {
  css: `/styles/main.css?v=${itemHash}`,
  js: `/scripts/app.js?v=${itemHash}`,
  json: `/api/item/${itemId}.json?v=${itemHash}`
};

// When item changes, hash changes, URLs change, browser fetches new version

🐛 Part 5: Debugging Stale Cache Issues

Identifying Cache Problems

// Middleware to detect cache issues
export async function middleware(req, res, next) {
  const cacheKey = req.url;
  const cachedAt = req.headers['x-cache-date'];
  const now = Date.now();
  
  // Check if content is stale
  if (cachedAt && (now - parseInt(cachedAt)) > 300000) {
    // More than 5 minutes old
    console.warn(`Stale content served: ${cacheKey}`);
  }

  // Add diagnostic headers
  res.setHeader('X-Cache-Date', now.toString());
  res.setHeader('X-Cache-Status', 'HIT/MISS');
  res.setHeader('X-Cache-Age', (now - parseInt(cachedAt || 0)).toString());

  next();
}

Browser DevTools Debugging

// Log cache status in browser console
fetch('/api/page', {
  headers: {
    'Accept-Encoding': 'gzip',
    'User-Agent': navigator.userAgent
  }
}).then(response => {
  console.log('Cache Headers:', {
    cacheControl: response.headers.get('cache-control'),
    etag: response.headers.get('etag'),
    lastModified: response.headers.get('last-modified'),
    age: response.headers.get('age'),  // CDN age
    via: response.headers.get('via')   // CDN provider
  });
});

Troubleshooting Matrix

🎯 Conclusion

Sub-second response times require coordinated caching across multiple layers. Start with ISR and CDN cache headers, then add sophisticated invalidation as needed. Monitor continuously and adjust TTLs based on real user data.

The Challenge

• Content teams live in Excel.
• Developers prefer structured formats like JSON.
• Sitecore needs clean, validated data to create content items at scale.

Traditional approaches meant exporting JSON files, juggling temp folders, and scripting one-off transformations. I wanted a system that was repeatable, auditable, and fully API-driven.

The Architecture

1. Excel in Sitecore Media Library → Editors upload workbooks as media items.
2. GraphQL Query → Resolve the media item URL via Sitecore GraphQL.
3. Next.js API (with xlsx) → Download, parse, normalize headers, return JSON.
4. PowerShell + SPE → Call API, validate, and upsert items into Sitecore.

This creates a seamless Excel → JSON → Sitecore pipeline.

Step 1 — GraphQL to Resolve the Media Item

We start by resolving the Excel file stored in the Media Library:

query ExcelMedia($id: String!) {
  item(path: $id, language: "en") {
    ... on MediaItem {
      id
      name
      extension
      url: mediaUrl
    }
  }
}

This gives us the download URL for the Excel file.

Step 2 — Next.js API: Parse Excel into JSON

The API fetches the media binary, parses it with xlsx, and maps it to clean JSON. Features include:

• Column mapping dictionary (Page Title → Title)
• Validation (required fields)
• Duplicate detection (ExternalId or Title)
• Dry-run mode
• Sheet selection (?sheet=LandingPages)

import * as XLSX from "xlsx";

const COLUMN_MAP = {
  "title": "Title",
  "page title": "Title",
  "summary": "Summary",
  "body": "Body",
  "content": "Body",
  "category": "Category",
  "external id": "ExternalId",
  "id": "ExternalId"
};

// Normalize + validate rows
type MappedRow = { Title: string; Summary?: string; Body?: string; Category?: string; ExternalId?: string };

function mapRow(raw: Record<string, unknown>): MappedRow {
  const mapped: Partial<MappedRow> = {};
  for (const [k, v] of Object.entries(raw)) {
    const key = String(k).toLowerCase().trim();
    const field = COLUMN_MAP[key];
    if (!field) continue;
    mapped[field] = String(v ?? "");
  }
  mapped.Title = (mapped.Title ?? "Untitled").trim();
  mapped.Category = mapped.Category ?? "General";
  return mapped as MappedRow;
}

export async function GET(req: Request) {
  const url = new URL(req.url);
  const mediaId = url.searchParams.get("mediaId");
  const dryRun = url.searchParams.get("dryRun") === "true";

  // 1. Resolve Media URL via GraphQL (omitted here for brevity)
  // 2. Fetch binary
  // 3. Parse workbook

  const wb = XLSX.read(/* arrayBuffer */, { type: "array" });
  const ws = wb.Sheets[wb.SheetNames[0]];
  const raw = XLSX.utils.sheet_to_json(ws, { defval: "" });

  const mapped = raw.map(mapRow);

  return Response.json({
    dryRun,
    count: mapped.length,
    data: mapped
  });
}

Step 3 — PowerShell Importer

The PowerShell script calls the API, validates rows, and upserts into Sitecore. It respects dry-run mode and reports created, updated, skipped, failed.

param(
  [string]$MediaId = "media:/sitecore/media library/Your/Path/content.xlsx",
  [string]$ApiBase = "https://yourapp.com/api/import/parse-excel",
  [switch]$DryRun
)

$endpoint = "$ApiBase?mediaId=$([uri]::EscapeDataString($MediaId))" + ($(if ($DryRun) { "&dryRun=true" } else { "" }))
$response = Invoke-RestMethod -Uri $endpoint -Method Get

$parentPath = "master:/sitecore/content/YourSite/Migrated"
$templateId = "{TEMPLATE-GUID-HERE}"

foreach ($row in $response.data) {
  $title = $row.Title
  $name  = [Sitecore.Data.Items.ItemUtil]::ProposeValidItemName($title)

  # Resolve existing by ExternalId or Title
  $item = $null
  if ($row.ExternalId) { $item = Get-Item "$parentPath/*" | Where-Object { $_["ExternalId"] -eq $row.ExternalId } | Select-Object -First 1 }
  if (-not $item) { $item = Get-Item "$parentPath/*" | Where-Object { $_["Title"] -eq $title } | Select-Object -First 1 }

  if (-not $item) {
    $item = New-Item -Path $parentPath -Name $name -ItemType $templateId
  }

  $item.Editing.BeginEdit()
  try {
    $item["Title"]      = $row.Title
    $item["Summary"]    = $row.Summary
    $item["Body"]       = $row.Body
    $item["Category"]   = $row.Category
    $item["ExternalId"] = $row.ExternalId
  } finally {
    $item.Editing.EndEdit()
  }
}

Hardening & Enhancements

• Dry-run mode → editors see validation errors without creating items.
• Row-level error reporting → API returns { rowNumber, messages } for invalid rows.
• Duplicate detection → prevents double imports by checking ExternalId/Title.
• Observability → counts, logs, and metrics pushed to dashboards.
• Security → protect API with signed tokens or IP allowlisting.

Why This Works

✅ Editors stay in their comfort zone (Excel in Media Library).

✅ Developers get a stable JSON contract.

✅ PowerShell focuses on item creation, not messy parsing.

✅ Re-runs are safe thanks to upserts + duplicate detection.

This isn’t just about moving content—it’s about building a reliable migration engine that’s reusable for future projects.

Final Thought

When migrations are API-driven, versioned, and validated at the edge, you get repeatability, safety, and speed. That’s exactly what this Next.js + PowerShell pipeline delivered.

This post will walk through a robust, production-ready solution: a custom Next.js Image Wrapper that not only gracefully handles all media from Sitecore but also intelligently renders SVGs as true inline svg markup.

Executive Summary

• The Problem: The default next/image component treats SVGs as raster images, limiting styling and DOM manipulation. We also need a bulletproof way to handle missing width, height, and alt attributes from Sitecore.
• Inline SVG vs. next/image: By rendering SVGs as inline <svg> markup, we gain full CSS control (e.g., currentColor for theming), enable accessibility hooks, and simplify DOM manipulation. For all other image types, we leverage the power of next/image for automatic optimization.
• Bulletproof Fallbacks: Our wrapper component provides sensible defaults for width and height if they are missing from the Sitecore Media Library, preventing Cumulative Layout Shift (CLS) and ensuring consistent layouts.
• Key Outcomes: This approach leads to superior performance (no extra network requests for styling), enhanced accessibility, and a more maintainable, consistent frontend architecture. It’s about building a predictable and resilient component system.

The Problem

Sitecore’s Media Library is a fantastic tool for managing digital assets. It provides URLs for images, but when it comes to SVGs, a URL is often not enough. A standard <img> tag or next/image component treats the SVG file just like a PNG or JPG. We lose:

• Styling with CSS: Can’t use fill, stroke, or color to change the icon's appearance based on state or theme. This is critical for design systems and Dark Mode.
• DOM Interaction: No way to programmatically manipulate the SVG's internal paths or elements with JavaScript.
• Accessibility: The alt text is on the wrapper <img> tag, but you can’t add rich accessibility attributes like aria-labelledby or role="img" directly to the <svg> itself.
• Performance: The browser makes an extra network request to download the SVG, even if it's a tiny icon, instead of having the markup directly in the DOM.

On top of this, CMS authors often forget or don't know to fill in the width, height, or alt fields for an image, leading to layout shifts and accessibility violations. We need a way to enforce consistency without manual intervention.

The Solution: Architecture Overview

Our solution is an intelligent wrapper component that sits in front of the standard next/image. Its primary job is to inspect the src URL and make a critical decision: should this be a flexible, inline <svg> or a performant, optimized <Image>?

Here’s the decision flow:

props (field, width, height)
         └─> isSVG? (check file extension)
         |   └─> is in Experience Editor or Preview mode? -> <NextImage />
         |   └─> else -> fetch SVG content on the server -> render <SVGInline />
         |
         └─> else (e.g., .jpg, .png)
             └─> has all dimensions? -> <NextImage />
             └─> else (missing dimensions)
                 └─> is in Experience Editor? -> render red warning + <NextImage />
                 └─> else -> render empty tag to prevent layout shift

This architecture ensures we get the best of both worlds: the power of inline SVGs where we need it and the performance benefits of next/image for everything else. The fallback logic for missing dimensions is a critical safety net that prevents layout shifts (CLS) and provides clear feedback to content authors in the editor.

Code Walkthrough

Let's dissect the code files to see how this all comes together.

NextImageExtended.tsx

This is our main wrapper component. It's the "brain" that makes all the decisions.

File Name & Role: NextImageExtended.tsx. This component serves as a drop-in replacement for the default Sitecore JSS NextImage component. Its primary responsibility is to orchestrate the rendering logic based on the image's properties.

Key Exports:

• NextImageExtended: The core component that handles the rendering logic.
• NextImageProps: A TypeScript interface to define the expected props, ensuring type safety.

Code:

import useIsEditing from '@/hooks/useIsEditing';
import {
  ImageField,
  LayoutServicePageState,
  NextImage,
  useSitecoreContext,
} from '@sitecore-jss/sitecore-jss-nextjs';
import SVGInline from './SVGInline';

type NextImageProps {
  field?: ImageField;
  width?: number;
  height?: number;
}

const NextImageExtended = (props: NextImageProps): JSX.Element => {
  const { sitecoreContext } = useSitecoreContext();
  const isEditing = useIsEditing();
  const isPreview = sitecoreContext.pageState == LayoutServicePageState.Preview;

  if (!!props.width && props.field?.value) {
    props.field.value.width = props.width;
  }
  if (!!props.height && props.field?.value) {
    props.field.value.height = props.height;
  }
  const hasEmptyDimension =
    props?.field?.value?.src !== undefined &&
    (props.field?.value?.width === undefined ||
      props.field?.value?.width === '' ||
      props.field?.value?.height === undefined ||
      props.field?.value?.height == '');

  if (props.field?.value?.src?.includes('.svg') && !(isEditing || isPreview)) {
    let src = props.field?.value?.src;
    src = '/api/fetchSvg?url=${encodeURIComponent(src)}';
    return <SVGInline src={src} />;
  } else if (props.field?.value?.src?.includes('.svg') && hasEmptyDimension) {
    props.field.value.width = 50;
    props.field.value.height = 50;

    return <NextImage {...props} />;
  } else if (hasEmptyDimension) {
    if (isEditing) {
      return (
        <>
          <span style={{ color: 'red' }}>Fill in image dimensions</span>
          <NextImage {...props} />
        </>
      );
    } else {
      return <></>;
    }
  } else {
    return <NextImage {...props} />;
  }
};

export default NextImageExtended;

Why this matters:

• Experience Editor Exemption: We intentionally don't render inline SVGs in the Experience Editor. This is a crucial design choice. The editor often requires a specific <img> tag structure to enable its rich-text and image editing capabilities. The useIsEditing() and useSitecoreContext() hooks are the perfect way to make this distinction, ensuring the authoring experience is not broken.

• Server-Side Fetching: The src is rewritten to /api/fetchSvg. This is a powerful move. By fetching the SVG content on the server side (via a Next.js API route), we can get the raw markup before the component is rendered. This is essential for server-side rendering (SSR) and Incremental Static Regeneration (ISR). The <SVGInline> component then renders this already-fetched and sanitized markup. This avoids a client-side fetch, improving performance.

• Handling Missing Dimensions: The hasEmptyDimension check is our fallback logic.

• Preventing CLS: Setting default dimensions prevents a massive layout shift. next/image requires these values to calculate the aspect ratio, which is key to preventing CLS.

• Content Author Feedback: In editing mode, we show a red warning. This isn't just a band-aid; it's a user experience improvement for the content author, teaching them that dimensions are important.

• Graceful Degradation: In production, if dimensions are still missing, we just render an empty <></> fragment. This is an opinionated choice: better to render nothing than to cause a massive layout shift or a broken layout.

fetchSvg.ts

This is our Next.js API route. It's a simple, single-purpose utility.

File Name & Role: fetchSvg.ts. This file defines a serverless function that lives in the /pages/api directory (or /app/api in Next.js 13+). Its sole purpose is to securely fetch the raw content of a given SVG URL.

Key Exports:

• handler: The default export that serves as the API route.

Critical Code Paths:

import { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { url } = req.query;

  if (!url) {
    res.status(400).json({ error: 'Missing URL parameter' });
    return;
  }

  try {
    const response = await fetch(url as string);

    if (!response.ok) {
      res.status(response.status).json({ error: 'Failed to fetch SVG' });
      return;
    }

    const data = await response.text();
    res.setHeader('Content-Type', 'image/svg+xml');
    res.status(200).send(data);
  } catch (error) {
    res.status(500).json({ error: 'Internal Server Error' });
  }
}

Why this matters:

• Security First: By using an API route as a proxy, we can sanitize the SVG content before it reaches the client. While this code doesn't show it, a real-world implementation should use a library like dompurify on the data to strip out any malicious <script> tags or on* attributes. Never render raw SVG markup from an untrusted source.
• Caching and Optimization: This API route can be cached by a CDN or Next.js, meaning the SVG content is only fetched from Sitecore once. This is a huge performance win for repeat visits.
• Cross-Origin Headers: This route handles any potential cross-origin (CORS) issues between your Next.js application and the Sitecore Media Library, as it acts as a server-side intermediary.

Migration Checklist

Ready to adopt this into your project? Here's a quick checklist:

1. Create the files: Add NextImageExtended.tsx, SVGInline.tsx (a simple component that takes src as props and renders the inner HTML), and the fetchSvg.ts API route.
2. Add Types & Helpers: Ensure you have the necessary types and the useIsEditing hook.
3. Update your components: Find and replace all instances of <NextImage ... /> with <NextImageExtended ... />.
4. Sanitize: Integrate a sanitation library like dompurify into the fetchSvg.ts route for security.
5. Test: Verify that images and SVGs render correctly in both production and Experience Editor modes. Ensure missing dimensions are handled gracefully.

By following this approach, you can deliver a more performant, accessible, and maintainable frontend experience for your Sitecore solution. It’s about being deliberate with our design choices and creating a component system that is both intelligent and resilient.

Let’s dive into how this integration is changing the game for digital marketers.

Why AI Content Optimization in XM Cloud is a Game-Changer

Creating high-performing, on-brand content at scale has always been a challenge. With Sitecore Stream’s AI integration in XM Cloud, marketers now have:

• Instant content generation – AI drafts text for headlines, paragraphs, and CTAs in seconds.
• Real-time optimization – Fix grammar, adjust tone, shorten or expand text with a click.
• Brand-aware AI – Ensures all content aligns with your brand guidelines (for Stream Premium users).
• Data-driven decisions – A/B test AI-optimized content to determine the best-performing version.

No more staring at a blank page—just faster, smarter content creation.

How AI Content Optimization Works in XM Cloud Pages

Generate & Refine Content in Seconds

Inside XM Cloud's Page Editor, simply:

1. Select any text component (headline, paragraph, CTA)
2. Click "Optimize Content" in the right-hand panel
3. Choose an action:
   • Improve writing (sharpens clarity & engagement)
   • Fix spelling & grammar (instant proofreading)
   • Make shorter / longer (condenses or expands text)
   • Change tone (adjusts voice for different audiences)
   • Translate (supports multiple languages)
   • Adhere to brand (applies brand guidelines if a Brand Kit is linked)

A/B Test AI-Optimized Content

Once you've generated an optimized version, you can:

Replace the original text immediately
Run an A/B/n test to see which version performs better

Example:

• Original: "Discover our latest product features."
• AI-Optimized: "Unlock the full potential of our newest innovations."
• Test both variants to see which drives more engagement

Personalize Content with AI

In Personalize mode, AI helps tailor content for different audience segments. Need a more formal tone for B2B visitors and a friendly one for B2C Stream adjusts dynamically.

Getting Started with AI Optimization in XM Cloud

Requirements:

• Sitecore Stream Premium (for AI content optimization)
• New CKEditor rich text editor enabled in XM Cloud
• JSS v22.1+ (for A/B/n testing)

Next Steps:

1. Enable Stream in XM Cloud (contact Sitecore if not yet activated)
2. Link a Brand Kit (for brand-aware optimizations)
3. Start optimizing! Select any text component and let AI enhance it

The Future of AI in Sitecore

This is just the beginning. Expect even deeper AI integrations, such as:

• Automated personalization (AI suggesting dynamic content variations)
• Predictive content scoring (AI forecasting engagement before publishing)
• Voice & visual brand alignment (AI ensuring multimedia stays on-brand)

Note: The points about future AI integrations in Sitecore are educated predictions based on Current Sitecore Product Direction and Sitecore's Existing AI Capabilities

Final Thoughts

Sitecore Stream's AI-powered content optimization in XM Cloud isn't just a productivity boost—it's a fundamental shift in how marketers and content creators create and optimize content. By combining AI speed, brand governance, and data-driven testing, Sitecore is helping teams work smarter, move faster, and drive better results.

Ready to transform your content workflow?
👉 Reach out to Sitecore or your implementation partner to enable Stream in XM Cloud today.

Challenges with Docker-Based Development

Initially, Sitecore developers utilized Docker-based development, which involved simulating XM Cloud's backend services locally. However, this approach presented several challenges:

• Incomplete Service Simulation: Not all XM Cloud services could be effectively replicated locally, limiting access to features like Pages, Forms, and Components.

• Platform Limitations: The reliance on .NET Framework necessitated Windows-based containers, restricting development to Windows machines and excluding macOS or Linux users.

• Resource Intensiveness: Running multiple containers demanded high-spec machines, leading to increased hardware requirements and potential performance issues.

• Slow Startup Times: Developers often faced prolonged startup durations as numerous containers initialized, hindering productivity.

• Limited Offline Development: An internet connection remained essential for authentication and content management tasks, even when working locally.

Advantages of the FED First Approach

The FED First approach addresses these challenges by allowing developers to run only the head application locally, connecting directly to the XM Cloud Preview Endpoint. This offers several benefits

• Full Access to Services: Developers can utilize all XM Cloud backend applications, including Pages, Forms, and Components, without local simulation.

• Cross-Platform Compatibility: By eliminating the need for Windows-specific containers, development becomes feasible on Windows, macOS, and Linux systems.

• Reduced Resource Requirements: With fewer applications running locally, developers can operate effectively on machines with lower specifications.

• Faster Startup Times: Launching the development environment is quicker, as it involves starting only the head application.

• Simplified Debugging: Connecting the local head application to production environments facilitates easier debugging with live data.

Considerations with the FED First Approach

While the FED First approach offers numerous advantages, it's important to acknowledge potential drawbacks

• Dependence on Internet Connectivity: Continuous access to the XM Cloud Preview Endpoint requires a stable internet connection, which may be a limitation in environments with unreliable connectivity.

• Integration Challenges: Coordinating with existing systems and processes might necessitate additional configuration and testing to ensure compatibility.

• Limited Backend Debugging: While front-end debugging is simplified, debugging issues originating in the XM Cloud backend requires relying on logs and potentially remote debugging tools provided by Sitecore.

• Initial Data Setup: Ensuring the XM Cloud environment has the necessary content and configurations for your front-end development might require additional effort upfront.

Conclusion

Sitecore's FED First approach streamlines the development process by addressing many of the limitations inherent in Docker-based development. By enabling direct connections to XM Cloud services and supporting cross-platform development, it offers a more efficient and flexible workflow. However, developers should consider factors such as internet dependency and potential integration challenges when adopting this approach.

For a practical demonstration of the FED First approach, refer to the following video:

Front-End First Development in XM Cloud - YouTube

Note: The insights presented are based on available information and may evolve with ongoing developments in Sitecore's methodologies.

The Challenge

Sitecore XM Cloud doesn't include out-of-the-box email notifications for workflow state changes. Since XM Cloud discourages server-side customizations, we need a cloud-native solution.

The Solution: Webhook Submit Actions

Webhook Submit Actions allow you to trigger HTTP calls when workflow actions occur—without writing server-side code. Here's how to set up email notifications when an item reaches the Approved state.

Step 1: Add a Webhook Submit Action

1. Navigate to your workflow:

   • Go to /Sitecore/System/Workflows in the Content Editor
   • Open the Approved state

2. Insert a Webhook Submit Action:

   • Right-click the state → Insert → Webhook Submit Action

3. Configure the Webhook:

   • Enabled: Check to activate
   • URL: Your API endpoint (e.g., Next.js/SendGrid email service)
   • Serialization: Choose JSON or XML (JSON recommended)

Step 2: Set Up Authentication (Optional)

If your API requires auth, create an Authorization Item under: /sitecore/System/Settings/Webhooks/Authorizations

Supported auth types: - ApiKey - Basic - Digest

Example Payload Sent to API

When the workflow triggers, Sitecore sends a JSON payload like this:

Step 3: Email API Example (Next.js + SendGrid)

Deploy this Next.js API to handle the webhook and send emails:

if (!payload.DataItem || !payload.UserName) {
  return res.status(400).json({ error: 'Invalid payload format' });
}

const msg = {
  to: process.env.NOTIFICATION_RECIPIENT || 'admin@yourdomain.com',
  from: process.env.SENDER_EMAIL || 'noreply@yourdomain.com',
  subject: 'Workflow Update: ' + payload.DataItem.Name + ' Approved',
  html:
    '<h2>Workflow Item Approved</h2>' +
    '<p><strong>Content Item:</strong> ' + payload.DataItem.Name + '</p>' +
    '<p><strong>ID:</strong> ' + payload.DataItem.Id + '</p>' +
    '<p><strong>Approved By:</strong> ' + payload.UserName + '</p>' +
    '<p><strong>Workflow:</strong> ' +  payload.WorkflowName + '</p>' +
    '<p><strong>Previous State:</strong> ' + (payload.PreviousState?.DisplayName || 'N/A') + '</p>' +
    '<p><strong>Comments:</strong> ' + (payload.Comments?.[0]?.Value || 'No comments provided') + '</p>' +
    '<p>Please review the item in <a href="' + process.env.SITECORE_APP_URL + '">Sitecore</a>.</p>',
};

await sgMail.send(msg);

return res.status(200).json({
  success: true,
  message: 'Notification sent successfully',
});

} catch (error) { console.error('Error processing workflow notification:', error); return res.status(500).json({ error: 'Failed to process notification', details: error instanceof Error ? error.message : 'Unknown error', }); } } `}

Final Thoughts

By combining Webhook Submit Actions with a lightweight API, you can implement workflow emails in XM Cloud while adhering to best practices. Extend this further with:

• Notifications for rejections or draft submissions
• Multi-channel alerts (e.g., Slack + email)

Pro Tip: Test your webhook with tools like webhook.site before connecting to email services.

What is Geospatial Search?

Geospatial search refers to the ability to filter and retrieve content based on geographical data, such as latitude and longitude. This functionality is essential for industries where proximity is important, such as retail, healthcare, real estate, and logistics. Sitecore’s search engine makes it easy to filter content based on location, offering users results that are directly relevant to their current or specified geographic area.

How to Implement Geospatial Search in Sitecore

In this section, we’ll walk through how to implement geospatial search using Sitecore's search API.

Step 1: Indexing Geospatial Data

To get started, we need to create a custom field in Sitecore to store geographical coordinates. In this case, we created a field named Coordinates with a GEO data type, which can store latitude and longitude values.

Here’s an example of indexing a record for a doctor with their location. In this case, I used Sitecore Search's PUSH source and Postman to push dummy data. The following JSON is the sample input used to feed the PUSH API via Postman:

This JSON document represents a doctor, with the coordinates field storing the latitude and longitude of their practice. This geospatial data will later be used to filter search results based on proximity.

Step 2: Modifying the Search API for Geo Filtering

Once the data is indexed, we need to filter search results based on the user’s location. The following code snippet demonstrates how to modify the Search API SDK to include geospatial filters:

const request = query.getRequest();
const geofilter = new FilterGeo('coordinates', radius, latitude, longitude).toJson();
geofilter['type'] = 'geoDistance';

// Conditionally add geo filter if coordinates are available
if (latitude && longitude) {
  request.setSearchFilter(
    new FilterAnd([new FilterEqual('name', 'Dr. John Doe'), geofilter])
  );
}

// Conditionally add source ID of PUSH Source
if (sourceId) {
  request.setSources([sourceId]);
}

} });`}

In this code, the latitude and longitude values represent the location of the user making the search. The FilterGeo function is used to filter the search results by geospatial data, with the geoDistance filter type ensuring that results are ordered based on proximity.

Why Geospatial Search is Important

Geospatial search is particularly valuable for businesses that depend on location-specific data. Here are some key reasons why implementing geospatial search can enhance your business:

1. Proximity-Based Results: Geospatial search allows users to find nearby services, stores, or content based on their current location, improving the overall user experience.

2. Personalized User Experience: By integrating location-based filtering, you can provide more relevant search results, ensuring that users find exactly what they need, when they need it.

3. Better Engagement: Providing users with content that’s relevant to their location can increase engagement, especially in industries such as retail and healthcare, where local presence is key.

4. Operational Efficiency: Geospatial search can streamline business operations by allowing for easy display and management of localized content, improving service delivery.

Conclusion

Geospatial search is a powerful feature in Sitecore that enhances the user experience by delivering more relevant and localized content. Whether you're working in retail, healthcare, or any other industry that relies on geographic data, implementing geospatial search can make a significant impact on your site's search functionality.

By leveraging Sitecore’s search API and incorporating geo filters into your queries, you can provide users with a more personalized and location-aware experience. As businesses continue to rely on geospatial data, integrating such features into your digital solutions will only become more critical for success.

This configuration can be utilized to improve the performance of Sitecore across various environments, ensuring that production instances are set up to deliver optimal results.

    <databases>
        <database id="web" role:require="ContentDelivery or Standalone">
            <securityEnabled>false</securityEnabled>
            <cacheSizes>
                <data>1000MB</data>
                <items>1000MB</items>
            </cacheSizes>
        </database>

        <database id="master" role:require="Standalone or ContentManagement">
            <cacheSizes>
                <data>1000MB</data>
                <items>1000MB</items>
            </cacheSizes>
        </database>
    </databases>
    
    <settings>
        <setting name="Analytics.AutoDetectBots" value="true" />
        <setting name="Analytics.Robots.IgnoreRobots" value="true" />
        <setting name="ContentTesting.AutomaticContentTesting.Enabled" value="false" />
        <setting name="Publishing.DeepScanRelatedItems" value="false"/>
        <setting name="Caching.AccessResultCacheSize" value="200MB" />
        <setting name="Counters.Enabled" set:value="false" />
        <setting name="ContentEditor.CheckHasChildrenOnTreeNodes" set:value="false" />
        <setting name="ContentEditor.CheckSecurityOnTreeNodes" set:value="false" />
        <setting name="Pipelines.Profiling.Enabled" set:value="false" />
        <setting name="Analytics.CookieLifetime" set:value="34310"/>

        <setting name="HtmlEditor.RemoveScripts" >
            <patch:attribute name="value">false</patch:attribute>
        </setting>

        <setting name="GeoIp.PerformLookup">
            <patch:attribute name="value" value="false" />
        </setting>
    </settings>
    
    <scheduling>
        <agent type="Sitecore.Tasks.CounterDumpAgent">
            <patch:delete />
        </agent>
        <frequency>02:00:00</frequency>
    </scheduling>
    
    <hooks>
        <hook type="Sitecore.Diagnostics.HealthMonitorHook, Sitecore.Kernel">
            <patch:delete />
        </hook>
        <hook type="Sitecore.Diagnostics.MemoryMonitorHook, Sitecore.Kernel">
            <patch:delete />
        </hook>
    </hooks>
    
</sitecore>

`}

Configuration Breakdown

Database Settings

• <securityEnabled>false</securityEnabled> in <database id="web">
  Disables security checks on the web database, which can improve performance by bypassing permission evaluations for public content.

  • Pros: Increases speed for content retrieval.
  • Cons: May pose a risk if sensitive content is mistakenly published.

• <cacheSizes> in <database id="web"> and <database id="master">
  Sets cache sizes for data and items on both databases, optimizing retrieval times.

  • Pros: Enhances performance by reducing database calls.
  • Cons: High memory usage may require monitoring to avoid memory issues.

Sitecore Settings

• <setting name="Analytics.AutoDetectBots" value="true" />
  Enables bot detection, filtering bot activity in analytics.

  • Pros: Improves analytics accuracy.
  • Cons: Could misclassify some legitimate users as bots.

• <setting name="Analytics.Robots.IgnoreRobots" value="true" />
  Ignores bot activity in analytics reports.

  • Pros: Maintains data integrity by excluding bots.
  • Cons: Risk of overlooking user behavior if real users are misclassified as bots.

• <setting name="ContentTesting.AutomaticContentTesting.Enabled" value="false" />
  Disables automatic content testing.

  • Pros: Reduces resource use by disabling unused features.
  • Cons: Limits A/B testing capabilities.

• <setting name="Publishing.DeepScanRelatedItems" value="false"/>
  Prevents deep scans of related items during publishing, which can enhance publish speed.

  • Pros: Shortens publishing times.
  • Cons: Potentially omits related items if dependencies exist.

• <setting name="Caching.AccessResultCacheSize" value="200MB" />
  Allocates 200MB to the access result cache, helping cache permission checks.

  • Pros: Speeds up access calculations.
  • Cons: Higher memory use.

• <setting name="Counters.Enabled" set:value="false" />
  Disables Sitecore counters, which track various metrics.

  • Pros: Frees up resources, optimizing performance.
  • Cons: Reduces ability to monitor performance metrics.

• <setting name="ContentEditor.CheckHasChildrenOnTreeNodes" set:value="false" />
  Disables child node checks in the Content Editor, reducing rendering time.

  • Pros: Speeds up Content Editor operations.
  • Cons: Tree view may lack structure information, which could impact navigation.

• <setting name="ContentEditor.CheckSecurityOnTreeNodes" set:value="false" />
  Disables security checks on tree nodes in Content Editor.

  • Pros: Enhances performance for content editors.
  • Cons: Security risks if sensitive content permissions are ignored.

• <setting name="Pipelines.Profiling.Enabled" set:value="false" />
  Disables pipeline profiling, saving resources by not tracking processing performance.

  • Pros: Improves response time and reduces load.
  • Cons: Limited visibility for pipeline-related debugging.

• <setting name="Analytics.CookieLifetime" set:value="34310"/>
  Sets the duration for analytics cookies.

  • Pros: Manages user session persistence.
  • Cons: Shorter cookie lifetimes may impact tracking consistency.

• <setting name="HtmlEditor.RemoveScripts"><patch:attribute name="value">false</patch:attribute></setting>
  Allows scripts to be included in HTML editor content.

  • Pros: Supports custom scripting in content.
  • Cons: Potential security risks if scripts are not sanitized.

• <setting name="GeoIp.PerformLookup"><patch:attribute name="value" value="false" /></setting>
  Disables GeoIP lookup, which can reduce load from location-based lookups.

  • Pros: Enhances performance by avoiding extra lookups.
  • Cons: Location-based content may be impacted if needed.

Scheduling

• Counter Dump Agent Deletion
  <agent type="Sitecore.Tasks.CounterDumpAgent"><patch:delete /></agent>
  Removes the CounterDumpAgent to reduce processing overhead.
  • Pros: Reduces load by eliminating non-essential monitoring.
  • Cons: Reduces insight into counters.

Hooks

• Health Monitor Hook Deletion
  <hook type="Sitecore.Diagnostics.HealthMonitorHook, Sitecore.Kernel"><patch:delete /></hook>
  Removes Health Monitor Hook, saving resources.

  • Pros: Reduces resource consumption.
  • Cons: Misses out on automated health monitoring.

• Memory Monitor Hook Deletion
  <hook type="Sitecore.Diagnostics.MemoryMonitorHook, Sitecore.Kernel"><patch:delete /></hook>
  Disables Memory Monitor Hook to avoid memory monitoring overhead.

  • Pros: Saves resources.
  • Cons: Undetected memory issues could affect performance.

Ensure to thoroughly test configurations before production deployment, especially if disabling features essential for monitoring or analytics.

Problem Statement

When building headless JSS sites, you often need to expose certain site settings or global configuration data from the Sitecore SXA Settings node to the front-end. However, the out-of-the-box Sitecore Layout Service primarily focuses on delivering route details (placeholders, data sources, fields, etc.), which may not fully cover the broader configuration needs.

In such cases, using GraphQL to query site-specific settings and integrating the results into the page-props is a reliable approach.

The Solution

To address this requirement, we can extend the Sitecore page-props to include site-specific settings. The approach involves:

1. Extending the SitecorePageProps type to include site settings.
2. Creating a GraphQL service to query and fetch the settings items.
3. Adding a new plugin to the page-props-factory to populate the site settings into the props for every page.

Let's walk through the implementation step-by-step.

Implementation Steps

Step 1: Extend the SitecorePageProps Type

The first step is to extend the SitecorePageProps type to include a new property for site settings. We modify the src/types/props/page-props.ts file and add a new variable:

Here, we introduce a new property called SiteConfigurations of type SiteSettingFields, which will hold the site settings data.

Step 2: Create a GraphQL Service to Fetch Settings

Next, we create a service to handle GraphQL queries and fetch the settings fields. We’ll create a new file called settings-service.ts inside src/lib/page-props-factory/services.

const data = await this.myGraphQLClient.request<{
  sitesettings: {
    item: {
      contentRoot: {
        children: SiteSettingFields;
      };
    };
  };
}>(query);

return data.item.rendered;

private getQuery(siteName: string, language: string) { return `query { sitesettings: layout(site: "${siteName}", routePath: "/", language: "${language}") { item { contentRoot: parent { children(includeTemplateIDs: "{54BC031B-293F-46F6-8F98-CB4A9B37BDE2}") { results { sampleField: field(name: "sampleField") { jsonValue } } } } } } }`; } }`}

In this example:

• We use the GraphQLClient to execute a query against the Sitecore GraphQL endpoint.
• The query retrieves the children of the settings node, filtering by template ID ({54BC031B-293F-46F6-8F98-CB4A9B37BDE2}) and selecting the relevant fields.
• The sampleField is an example field from the settings that we want to expose.

This service is designed to fetch the site settings from the settings node, specifically tailored for each site.

Step 3: Add a New Plugin to the Page-Props Factory

Now, we integrate the site settings into our page-props using a custom plugin. We create a file called get-settings.ts inside src/lib/page-props-factory/plugins:

if (siteSettings != null && props != null) {
  props.SiteConfigurations = siteSettings ?? {};
}

return props;

export const getSiteSettingsPlugin = new GetSiteSettingsPlugin();`}

Plugin Explanation

• Order Property: The order = 2 ensures that this plugin runs after the core plugins (e.g., normal-mode and preview-mode). This is crucial because it allows us to populate the settings data before any layout data is processed.

• Settings Fetching: We call the fetchSettings method to retrieve the settings data based on the site name and locale. The resulting data is stored in the SiteConfigurations property within props, making it accessible across the application.

Optimization Considerations

Since this GraphQL query runs on every page render, caching the results is recommended to avoid redundant requests and improve performance. Implementing caching at either the service or plugin level can significantly optimize the solution.

Conclusion

This approach gives you a clean and extensible way to expose site settings from the SXA settings node to your Next.js frontend. By integrating GraphQL queries into the page-props factory and leveraging custom plugins, we can make site configurations accessible across every page in the application.

Feel free to enhance this solution further with caching strategies or by extending the settings to include more complex data structures. Happy coding!

The Setup

In this scenario, the public URLs were routed through Azure Application Gateway before reaching the internal Sitecore servers:

• User Request (CM): https://cm.cdn.xyz.com → Azure Application Gateway → https://cm.xyz.com (internal CM URL)

However, this setup presented some issues, as Sitecore’s out-of-the-box configuration isn’t fully equipped to handle such complex routing seamlessly.

Issue

Misalignment in URLs: The login redirects and callbacks during authentication often landed on the internal URLs (https://cm.xyz.com) rather than staying within the proxy URLs (https://cm.cdn.xyz.com), and hence produces invalid request error.

The Three-Step Solution

To resolve these issues, a three-step solution was implemented:

1. Install the "Application Gateway Host Rewrite" Extension

The first step is to ensure that the host headers are correctly rewritten so that Sitecore picks up the appropriate URLs. We installed the Application Gateway Host Rewrite extension on the CM App Service. This extension allows the Azure Application Gateway to rewrite the host headers for incoming requests, ensuring that IdentityServer4 picks up the correct host (https://cm.cdn.xyz.com), even after the requests have passed through the gateway.

2. Update Sitecore Identity Server confguration

The next step involves updating the Sitecore Identity Server configurations to allow communication from all relevant domains.

1. Open the \Config\production\Sitecore.IdentityServer.Host.xml file in the Sitecore Identity Server site root.
2. Locate the <AllowedCorsOrigins> tag and update it to include all the necessary domains that need to communicate with IdentityServer. Separate each domain using the | symbol.

For example, in an Azure QA environment with both CM and CD app services, the configuration might look like this:

3. Add a Rewrite Rule in CM’s web.config

Lastly, we added a rewrite rule in the web.config of the Content Management instance to handle URL rewrites correctly for outbound responses. Here’s the rule that was applied:

This rule ensures that any HTTP redirect responses are transformed to use the correct HTTPS endpoint (https://cm.cdn.xyz.com) and that the responses maintain consistency with the proxied URL.

Wrapping Up

By leveraging the Application Gateway Host Rewrite extension and carefully configuring rewrite rules, we were able to seamlessly integrate Sitecore CM and IdentityServer in a complex proxy/CDN environment. These adjustments allowed the client’s Sitecore environment to maintain consistent URLs throughout the authentication flow, improving the user experience and eliminating issues caused by internal vs. external URL mismatches.

This setup highlights the importance of understanding how Sitecore’s configurations interact with reverse proxies and CDNs, especially when dealing with environments hosted in Azure.

Use Case: Indexing Approved PDFs with Public URLs

In this post, we explore a scenario where we needed to index only approved PDF documents from Content Hub that have public URLs. We leveraged the Scroll API to retrieve and process a large number of results efficiently.

Using the Scroll API

The Scroll API is a powerful tool for retrieving extensive results from a single query without the limitations of traditional pagination. Unlike standard queries, it does not support the skip parameter and relies on retrieving the next page through the resource link. This allows continuous paging until no more results are available.

Here’s the Scroll API query we used:

GET /api/entities/scroll?query=Definition.Name=='M.Asset' AND Parent('AssetMediaToAsset').id==1057 AND Parent('FinalLifeCycleStatusToAsset').id==544&sort=createdOn&order=Asc

This query retrieves assets defined as 'M.Asset' and filters them to those associated with specific media and lifecycle status IDs.

Filtering for Approved PDFs

To further refine our results to only include approved PDF assets, we used the following filters:

• PDF Assets: Parent('AssetMediaToAsset').id==1057
• Approved Assets: Parent('FinalLifeCycleStatusToAsset')==544

Adding these filters to our query ensured that only approved PDF assets were returned. Although these IDs are typically standard across all Content Hub instances, it's important to verify them in your own Content Hub instance before using them in queries. You can locate the asset media type IDs under Taxonomy Management within Content Hub.

Retrieving Public URLs of an Asset

To include the public URLs of the PDFs in the index, we had to call additional APIs. For each asset returned by the Scroll API, we used the following endpoint to get all API URLs of the public links:

GET /api/entities/{assetId}/relations/AssetToPublicLink

The response provides the actual API links needed to obtain the public URL. Here’s an example response:

{
    "children": [
        {"href": "/api/entities/303872"},
        {"href": "/api/entities/235003"}
    ],
    "inherits_security": true,
    "self": {"href": "/api/entities/31999/relations/AssetToPublicLink"}
}

We then called each API link to retrieve the public URL.

Indexing Data into Coveo Using Push APIs

Step 1: Create the File Container

1. Obtain Access Token: Ensure it has Privileges / Organization / Organization = View.

2. Gather Information:

   • OrganizationId: Found in your Coveo Platform.
   • useVirtualHostedStyleUrl: Set to true.

3. Create File Container:

   • POST Request:

     POST https://api.cloud.coveo.com/push/v1/organizations/<OrganizationId>/files?useVirtualHostedStyleUrl=true
     Content-Type: application/json
     Accept: application/json
     Authorization: Bearer <AccessToken>
     

   • Response: Contains uploadUri, fileId, requiredHeaders.

Step 2: Upload Data to File Container

1. Prepare JSON Data: Structure your data using the addOrUpdate array.

   {
       "addOrUpdate": [
           {
               "m_title": "Example Title",
               "m_overview": "Description",
               "documentId": "http://example.com",
               "data": "Content",
               "fileExtension": ".txt"
           }
       ]
   }
   

2. Upload Data:

   • PUT Request:

     PUT <uploadUri - From Step 1>
     Content-Type: application/octet-stream
     x-amz-server-side-encryption: AES256
     

   • Body: Your JSON data.

Step 3: Push File Container to Push Source

1. Push Data:

   • PUT Request:

     PUT https://api.cloud.coveo.com/push/v1/organizations/<OrganizationId>/sources/<SourceId>/documents/batch?fileId=<fileId>
     Content-Type: application/json
     Authorization: Bearer <AccessToken>
     

2. Response: Should be null with a 202 Accepted status if successful.

Pseudo Implementation

With the necessary data gathered, we could proceed to index the content into Coveo. Below is a sample implementation in C#:

// Process each item in contentHubItems  
foreach (var item in contentHubItems)
{
    try
    {
        // Get Public link of the content hub Item
        var publicLink = GetAssetPublicLink(item.assetToPublicLink);
        
        // Parse content hub item required information to coveo model
        List<CoveoItem> coveoItemsModel = new List<CoveoItem>();
        CoveoItem coveoObject = GetCoveoObject(publicLink, item);
        coveoItemsModel.Add(coveoObject);
    }
    catch (Exception ex)
    {
        // Log Error
    }
}

// Try to push items to Coveo
if (coveoItemsModel.Count > 0)
{
    var coveoIPushModel = new CoveoItemsModel
    {
        addOrUpdate = coveoItemsModel
    };
    
    var containerInfo = CoveoHelper.CreateFileContainer();
    CoveoHelper.UploadConetntsToContainer(containerInfo.uploadUri, containerInfo.requiredHeaders.XAmzServerSideEncryption, coveoIPushModel);
    CoveoHelper.PushContainerToSource(containerInfo.fileId, containerInfo.requiredHeaders.XAmzServerSideEncryption);
}

// Recursively process next page if recursive flag is true
if (recursive && contentHubItems.next != null && !string.IsNullOrEmpty(contentHubItems.next.href))
{
    Process(contentHubItems.next.href);
}

}`}

Conclusion

By leveraging the Scroll API and additional API calls for public URLs, we were able to effectively index approved PDF documents from Sitecore Content Hub into Coveo. This approach ensures that only the necessary and approved assets are indexed, optimizing the search experience.

Feel free to use and adapt this approach for your own Sitecore Content hub and Coveo integrations.

Modular Component Architecture for Improved Maintainability and Reusability

A core aspect of the enhancements involves restructuring the codebase to utilize separate components for facets, pagination, sorting, and search results. This shift towards a modular component architecture offers several advantages:

Enhanced Maintainability:

Separating components fosters a well-organized codebase. This improves code readability and understanding, making it easier for developers to maintain and extend the functionalities in the future.

Increased Reusability:

Individual components can be reused across different parts of your application. This promotes code consistency and reduces development time by eliminating the need to rewrite code for similar functionalities.

Facet Refinement

Finding the exact product or information can be challenging, especially when dealing with a vast number of facets. To address this, I've introduced "show more" and "show less" functionality for facets. This allows users to control the number of facets displayed at once, preventing them from feeling overwhelmed by an excessive number of options. Additionally, facet filtering has been implemented, enabling users to refine their search results with greater precision.

This following component, FacetList, renders a list of facet values with filtering capabilities and a show more/show less feature. It receives props such as selectedFacetsToRender, facet, and facetsnumbertoshow, and dynamically filters the facet values based on user input. The component allows users to toggle the visibility of facet values and efficiently manage large lists by displaying only a subset at a time.

// Filter the array based on the input keyword
const updatedItems = facet.value.filter((item) =>
  item.text.toLowerCase().includes(inputKeyword)
);
setFilteredItems(updatedItems);

      {filteredItems.length > minNumberOfItemsToShow && (
        <div className="retractable-actions">
          {numberOfItemsToShow < totalItems && (
            <a href="#" className="retractable-toggle"
              onClick={(e) => {
                e.preventDefault();
                handleShowMore();
              }} > Show More{' '}
            </a>
          )}
          <br />
          {numberOfItemsToShow > minNumberOfItemsToShow && (
            <a href="#" className="retractable-toggle"
              onClick={(e) => {
                e.preventDefault();
                handleShowLess();
              }} > {' '} Show Less
            </a>
          )}
        </div>
      )}
    </AccordionFacets.Content>
  </AccordionFacetsStyled.Facet>
</>

export default FacetList;`}

Sharable Search Queries

Imagine collaborating with colleagues on research or revisiting a complex search later. The implemented mechanism to append facet selections and page numbers to the query string makes this a reality. Users can now generate URLs that include preselected facets and specific pages, Simply revisit the shared URL, and your desired search criteria are instantly applied.

Following is the function responsible to generate query string and append in Query string, called when any facet value is clicked.

This TypeScript function, manages the modification of facet-related search parameters in a URL query string. It parses the current query parameters, updates facet values based on user actions (such as selecting or deselecting options), and generates an updated URL with the modified parameters, ultimately navigating to the new URL

Open-Source Contribution and Continued Development

All of the enhancements mentioned above are included in a pull request submitted to the forked GitHub repository: https://github.com/mgnventures/Sitecore-Search-TS-SDK-Starter-Kit/pull/1 . This pull request provides a detailed overview of the changes and facilitates the integration of these improvements into the forked Sitecore Search SDK Starter Kit.

I believe these enhancements will significantly improve the Sitecore Search SDK Starter Kit, providing developers with a more efficient development experience and empowering users with a more intuitive and productive search experience. If you're interested in learning more or contributing to this project, feel free to visit the GitHub repository.

Prerequisites

Before proceeding, ensure the following prerequisites are met:

• A Sitecore search account with initial configuration set up on Customer Engagement Console (CEC).
• Sitecore headless Next.js solution running on your local environment.
• Installation of necessary packages:

Configuration Steps

1. Create Source in CEC

Follow the steps outlined in the official documentation to create a source in CEC.

2. Configure Suggestions Blocks

Ensure that suggestions blocks have a field named title_context_aware. Refer to the documentation for configuration details.

3. Setup Sorting Options

Configure sorting options to include featured_desc and featured_asc criteria as per the documentation.

4. Preconfigured Widgets

Ensure that the following widgets are created beforehand:

• Search Results Page
• Search Results
• Preview Search

Code Leveraging Steps

1. Download or clone the Sitecore Search SDK Starter Kit repository.
2. Copy the following folders from the starter kit's src folder to your Sitecore Next.js solution's src folder:
   • Contexts
   • Data
   • Hocs
   • Hooks
   • Themes

3. Create a new folder named widgets in your solution and copy the PreviewSearch and SearchResults folder along with Utils.tsx file from the starter kit.

4. We might face formatting issue in our copied tsx files, for this we can update .prettierrc file to handle formatting issues, set the endOfLine value to auto

5. Create environment variables in the .env file:

6. Update the _app.tsx file to integrate the widget provider.

Add necessary imports.

add following const in within the main function. {const { language, setLanguage } = useLanguage();}

Wrap language context and widget provider with <I18nProvider /> and Supply environment variables for customer key and API key, final outcome should look like as shown in the screenshot below:

7. Replace references to react-router-dom with @sitecore-jss/sitecore-jss-nextjs in Styled.ts file under SearchResults widget folder.

8. Replace useNavigate import from react-router-dom with next/router and fix all references accordingly, whereever it is being used.

9. Create a Search rendering in Sitecore and implement it in your Next.js solution.

   • Create a Search.tsx file under components/search folder.
   • Call the Search results widget in the Search.tsx file.
   • Wrap the export with withPageTracking hoc, this will enable tracking user analytics.
   • Example implementation:

export default withPageTracking(Search);`}

Now, you're ready to drop the search component on any page from the Experience Editor and enjoy the final outcome if the source and facets are configured properly in the CEC portal.

Conclusion

By following these steps, you can seamlessly leverage the Sitecore Search SDK Starter Kit into your Sitecore Next.js solution. With proper configuration and implementation, you can enhance search functionality and improve user experience, and update the styling of search components as per the site theme.

Understanding the Need for Migration

• Collaboration between developers and system administrators often involves experimentation and configuration changes.
• As deployments grow, efficient migration between Coveo organizations becomes crucial for consistency.
• Replicating production settings for new development iterations requires a streamlined migration process.

Migrating Your Configuration with Resource Snapshots

Coveo's Resource Snapshot feature allows you to take control of your migration. With snapshots, you can copy the configuration of various resources, including:

• Query pipelines
• Indexing pipeline extensions
• Hosted search pages
• Coveo Machine Learning models

This lets you quickly set up your new organization with the same functionality as your dev or qa oraganizations.

Important Considerations for Snapshots

While snapshots are a powerful tool, it's important to understand their limitations:

• Not all resource types are currently supported.
• Coveo does not offer an automated process to migrate organization data (such as user data).
• The snapshot can only copy the top 1,000 query suggestions from your old organization.
• Data like Usage Analytics cannot be migrated.

Professional Services: A Seamless Migration Option

For a more comprehensive migration experience, consider leveraging Coveo Professional Services. Coveo team can handle the entire process, ensuring a smooth transition with minimal disruption.

Creating a Snapshot

• Begin by creating a snapshot of resources in the source organization to capture the current configurations.

• Choose to include dependencies automatically to ensure all necessary resources are captured.
• Provide a descriptive name for easy identification and proceed to export the snapshot.

Exporting and Applying the Snapshot

• Export the created snapshot to the destination Coveo organization.
• Switch to the destination organization and apply the snapshot.
• Validate the snapshot to ensure all prerequisites are met and review any detected errors.
• Address errors before proceeding with the snapshot application.

Under the Hood: Snapshot Creation and Application

• A snapshot consists of a JSON file listing included resources and configurations.
• Coveo matches resource names in the snapshot with IDs in the destination organization to determine actions.
• This matching process ensures consistency and accuracy during snapshot application, preventing conflicts.

Conclusion

Efficiently migrating changes between cloud organizations in Coveo for Sitecore is essential for maintaining consistency and streamlining development workflows. By following these step-by-step instructions, organizations can replicate configurations across environments with ease, reducing manual effort and minimizing the risk of errors.

For further information and detailed guidance on managing resource snapshots, refer to the official Coveo documentation. Additionally, Coveo representatives are available to assist with specific inquiries and support ongoing optimization efforts.

Sitecore Search offers a comprehensive platform that allows you to incorporate predictive and personalized search experiences for your visitors. By leveraging the capabilities of Sitecore Search, you can request and retrieve data such as search results, facets, suggestions, and more, empowering you to build a highly tailored and relevant search experience.

Understanding the React SDK

What is the React SDK?

The React SDK from Sitecore Search is tailor-made for developers in the React ecosystem, including Next.js. It simplifies the integration of Sitecore Search into web apps, enriching the user experience with advanced search features. Developers can quickly enhance their applications with predictive search, personalized results, and more, thanks to the streamlined capabilities of the React SDK.

Key Components of the React SDK

The React SDK comprises two npm packages:

1. React Package: This package forms the foundation of the SDK, providing core functionality.

2. UI Package: Housing a plethora of UI components, the UI package equips developers with various composable to construct diverse user experiences seamlessly.

Getting Started with the React SDK

Installation and Configuration

To start utilizing the React SDK, we need to follow these fundamental steps:

1. Install the two required npm packages: React Package and UI Package. {`npm install --save @sitecore-search/react npm install --save @sitecore-search/ui `}
2. Wrap the React application with the Widget Provider component, furnishing the SDK with essential functionality, usually in Next JS application _app.tsx file is the root of the application.

Creating Search Components

Once the SDK is integrated into the React application, we can start building out search functionality, in order to communicate with Sitecore Search API we will use query hooks available in the JS SDK package, for search results we will be using useSearchResults query hook, this hook is used request and retrieve data for search results widgets. page, keyphrase, selectedFacets, itemsPerPage, and sortType.

Following is the basic example of its utilization:

export default SearchResultsStyledWidget; `}

in the above code line #69 is where our UI will be placed to create search experience like the implementation of facets, search results, pagination, we will disuss this in the next parts of the blog.

It is important to Convert a UI component into a widget component before adding it to pages or use.

To convert a component into a widget component, pass the UI component to the widget

Utilizing Supporting Resources

Documentation and Sample Repositories

Sitecore Search offers a comprehensive suite of resources to help developers in their journey to develop search experience:

1. Detailed SDK documentation and a Storybook instance for exploring UI components.

https://developers.sitecorecloud.io/search-sdk/react/latest/storybook/index.html?path=/story/introduction-introduction--page

2. Sample repositories, including a starter kit and the Developer Portal repository, provide practical examples and insights.

https://github.com/Sitecore/Sitecore-Search-JS-SDK-Starter-Kit

Conclusion

Incorporating Sitecore Search into React applications empowers developers to deliver enhanced search experiences, thereby elevating user satisfaction and engagement. By leveraging the React SDK and its accompanying resources, developers can streamline the implementation process and unlock the full potential of search functionality within their applications.

In the next blog post, I'll show you how to use the Sitecore Search SDK Starter Kit from GitHub repo to our Sitecore Next.js solution. Stay tuned for simple steps to create a great search experience!

Installing SharePoint On-Premises WebParts with PowerShell: Automating the installation of SharePoint On-Premises WebParts using PowerShell can significantly reduce administrative overhead. Below is a PowerShell script for installing a WebPart in a SharePoint On-Premises environment:

This script adds the solution file containing the WebPart to the SharePoint farm's solution store and deploys it globally across the farm.

Updating SharePoint On-Premises WebParts with PowerShell: Keeping SharePoint On-Premises WebParts up-to-date is essential for maintaining security and functionality. PowerShell can automate the process of updating WebParts across SharePoint farms. Here's a PowerShell script to update a SharePoint On-Premises WebPart:

This script updates the existing solution with the new version of the WebPart file.

Uninstalling SharePoint On-Premises WebParts with PowerShell: When SharePoint On-Premises WebParts are no longer needed, removing them is crucial to maintain system cleanliness and performance. PowerShell offers a straightforward approach to uninstalling SharePoint WebParts. Here's a PowerShell script to uninstall a SharePoint On-Premises WebPart:

This script uninstalls the solution containing the WebPart from the SharePoint farm and removes it from the solution store.

Conclusion: PowerShell is a powerful tool for managing SharePoint On-Premises WebParts, enabling administrators to automate the installation, updating, and uninstallation processes. By leveraging PowerShell scripts tailored to their specific needs, administrators can streamline WebPart management tasks, saving time and reducing the risk of errors. Whether deploying new WebParts, applying updates, or removing obsolete components, PowerShell provides a flexible and efficient solution for SharePoint On-Premises WebPart management.