
Agentic Studio is the part of SitecoreAI that demos well and integrates quietly. Sitecore introduced it on 4 November 2025 with the SitecoreAI announcement: a workspace where marketers and agents plan, create, and personalize, with 20 prebuilt agents and a visual builder for custom ones. A year later I am usually in the room as the person who has to explain why the agent's "successful" run did not change the website.

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:

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

The following step may only receive the id:

```json
{
  "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.

```ts
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.


Agentic Studio 101 for Developers — Where Agents Stop and Your Code Still Matters


Sitecore announced SitecoreAI on 4 November 2025. The press release was clear about the commercial story: SitecoreAI is the evolution of XM Cloud, current XM Cloud customers do not run a content migration, data stays in place, and Agentic Studio shows up on the same tenant. I have spent the year since that announcement on Next.js implementation work, and the question I still get in kickoff calls is the same one. If the upgrade is seamless, why does the head application feel like a project?

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 `rfkId`s 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?

```ts
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:

```ts
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.


SitecoreAI After XM Cloud — What Actually Changes for a Next.js Implementation Team


We recently deployed our Sitecore Next.js site on Netlify and ran into a frustrating caching problem. Even after revalidating pages, they stayed cached. The standard Next.js ISR revalidation just wasn't working reliably on Netlify's edge network, which meant content authors would publish updates and they wouldn't show up for users.

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:**
```ts
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:**
```ts
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:**
```powershell
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.



Next.js ISR + Netlify Cache Tag Purge for Sitecore Site Pages

Integrating SAP Customer Data Cloud with Sitecore XM Cloud Next.js - A Complete Implementation Guide


Working in Sitecore XM Cloud, I often noticed a gap: it can be difficult to quickly identify SEO and accessibility issues on a website page. Things like missing alt text, page titles, or improper heading structures often slip through the cracks. These may seem like small details, but they matter a lot for SEO and accessibility.

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.

![image](/images/post/xmcma-1.png)
---

## 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**

```bash
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**.  

![image](/images/post/xmcma-2.png)



- 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  

  ![image](/images/post/xmcma-3.png)

  ![image](/images/post/xmcma-4.png)

- 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**.  

![image](/images/post/xmcma-5.png)

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

```bash
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](https://github.com/mgnventures/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.


SEO Audit - Sitecore XM Cloud Marketplace App


When building headless Sitecore implementations with Next.js, securing specific pages or sections of your website is a common requirement. Whether it's user profiles, admin areas, or premium content, you need a robust way to verify authentication and redirect unauthorized users to a login page—without writing custom server-side code for each route.

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:

```typescript
// 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

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

### Step 2: GraphQL Service Implementation

The `GraphQLSecuredPagesService` fetches security mappings from Sitecore:

```typescript
// 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:

```typescript
// 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:

```bash
# 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:

```typescript
// 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

```bash
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:

```typescript
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.*



Secured Pages SXA Module for Next.js - Authentication Middleware Implementation


GraphQL performance is one of the most common pain points in Sitecore XM Cloud implementations. Developers report page load times degrading under traffic, inconsistent Experience Edge cache behavior, and unexpectedly high API costs. The problem often isn't GraphQL itself—it's how queries are structured.

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.

```graphql
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.

```graphql
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.

```graphql
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:**

```json
{
  "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.

```typescript
// 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.

```typescript
// 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.

```typescript
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.

---



GraphQL Query Optimization in Sitecore XM Cloud - Performance Patterns for Enterprise Scale


Running your **Next.js + Sitecore JSS** stack under HTTPS locally isn’t just about flashing a padlock icon—it keeps API contracts, cookies, and OAuth flows behaving exactly like they do in production. Below is the full workflow I use to stand up `https://localdev.corp.test` on Windows with **Caddy** and **mkcert**. Swap in your own domain as needed.

---

## 🧩 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:
   ```powershell
   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:
   ```powershell
   choco -v
   ```

---

## 🧱 2. Install Your Toolchain

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

```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.

```powershell
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:
   ```powershell
   ipconfig /flushdns
   ```

---

## 🛑 5. Free Up Ports 80/443

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

```powershell
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:

```powershell
Stop-Process -Id <PID> -Force
```

---

## 🧾 6. Author the `Caddyfile`

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

```caddy
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:

```powershell
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:

```powershell
caddy fmt --overwrite Caddyfile
```

---

## 🔁 10. Troubleshooting Cheat Sheet

| Problem | Why it happens | Quick fix |
| --- | --- | --- |
| Access denied on port 80/443 | IIS or another listener is running | Stop IIS with `Stop-Service W3SVC -Force` |
| Browser still warns “Not secure” | Trust store missing mkcert root | Re-run `mkcert -install` |
| Caddyfile warnings | Formatting or syntax issues | `caddy fmt --overwrite Caddyfile` |
| Domain won’t resolve | Hosts file wasn’t saved as admin | Re-open Notepad as admin, save again |

---

## 🔄 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

| Component | Why it matters |
| --- | --- |
| Chocolatey | Fast install + upgrades for Windows tooling |
| mkcert | Trusted local certificates with zero manual import steps |
| Caddy | Handles HTTPS termination and reverse proxying |
| Hosts file | Routes `localdev.corp.test` to `127.0.0.1` |
| IIS stop | Keeps ports 80/443 open so Caddy can bind |

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

---


Setting Up Local HTTPS with Caddy Reverse Proxy for Next.js JSS


Experience Edge is Sitecore's global CDN, but caching strategy makes the difference between millisecond response times and multi-second waits. Many implementations treat caching as an afterthought, resulting in stale content, cache invalidation issues, and poor Core Web Vitals.

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

```typescript
// 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

| Header | Purpose | Example |
|--------|---------|---------|
| `s-maxage` | CDN cache duration (seconds) | `s-maxage=300` (5 min) |
| `stale-while-revalidate` | Serve stale while refreshing | `stale-while-revalidate=600` |
| `Vary` | Cache key (vary by header) | `Vary: Accept-Encoding` |
| `ETag` | Content version identifier | `ETag: "abc123"` |
| `Last-Modified` | Last update timestamp | For conditional requests |

---

## ⚡ Part 2: Next.js ISR Configuration

### ISR (Incremental Static Regeneration)

ISR combines static generation with dynamic updates.

```typescript
// 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:

```typescript
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:

```typescript
// 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

```typescript
// 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

```graphql
# 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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

| Symptom | Cause | Solution |
|---------|-------|----------|
| Content always fresh but slow | Cache disabled | Check Cache-Control headers |
| Stale content shown | TTL too long | Reduce `s-maxage`, set revalidate |
| "Always different" responses | Cache key issues | Check `Vary` headers |
| High latency spikes | Cache miss storms | Enable stale-while-revalidate |
| Users see different content | Vary header missing | Add `Vary: Accept-Encoding` |


## 🎯 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.

---



Experience Edge Caching - Advanced Strategies for Sub-Second Response Times


Content migration projects are notoriously painful Excel files flying around email threads, editors losing track of versions, and developers drowning in manual imports. I recently implemented a workflow that **keeps Excel in Sitecore Media Library, transforms it to JSON with Next.js, and imports directly into Sitecore via PowerShell**. No temp files, no duplication, just clean automation.

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

```graphql
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`)

```ts
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**.

```powershell
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.

---


From Excel to Sitecore - My Streamlined Migration Workflow via PowerShell


Our team is consistently hitting a wall with next/image component. When a designer hands off a vector graphic, it gets flattened into a static img tag, completely stripping it of its inherent scalability and styling benefits. This isn't just a minor issue; it's a performance bottleneck, a hit to our dynamic styling capabilities, and a constant source of technical debt.

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:**
```tsx
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:**
```tsx
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.

Next.js Image Wrapper for Sitecore SVGs


Sitecore recently released Sitecore Stream, a powerful addition to its expanding suite of digital experience solutions. First introduced at last October’s Sitecore Symposium, this new tool is designed to help marketing teams create, manage, and optimize content more efficiently while ensuring brand consistency. As organizations scale their content production and personalization strategies, the demand for solutions that simplify workflows and uphold brand integrity continues to grow.

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

![image](/images/post/AItranslate.png)

### 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.* 




AI-Powered Content Creation in XM Cloud with Sitecore Stream


Sitecore's transition to the Front-End Development (FED) First approach represents a significant shift in developing with XM Cloud. This method emphasizes running the head application locally while connecting directly to the XM Cloud Preview Endpoint, streamlining the development process.

## 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](https://www.youtube.com/watch?v=hXPBtMHQMZw)

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

Embracing Sitecore's Front-End Development (FED) First Approach

When working with workflows in Sitecore, clients often request automated notifications to keep track of important state changes. The most common requirement is email alerts.

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

<Code language="json">
{`{
  "ActionID": "d6588964-7c88-4650-a2bf-27dff4297d65",
  "ActionName": "Approval",
  "Comments": [{"Key": "Comments", "Value": "Looks perfect!"}],
  "DataItem": {
    "Id": "2e97a681-05ed-4a1c-92b0-87343b1d0e27",
    "Name": "Home",
    "TemplateId": "c6a5d6a9-85a0-4acc-8337-074270364850"
  },
  "PreviousState": {
    "DisplayName": "Draft",
    "StateID": "{A0E3A221-B774-4473-B623-1312FB5645CE}"
  },
  "UserName": "sitecore\\admin",
  "WorkflowName": "Approval Workflow"
}`}
</Code>

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

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

<Code language="typescript">
{`// pages/api/workflow/notify.ts
import sgMail from '@sendgrid/mail';
import type { NextApiRequest, NextApiResponse } from 'next';

// Initialize SendGrid
sgMail.setApiKey(process.env.SENDGRID_API_KEY as string);

interface WorkflowPayload {
  ActionID: string;
  ActionName: string;
  Comments: Array<{
    Key: string;
    Value: string;
  }>;
  DataItem: {
    Id: string;
    Name: string;
    TemplateId: string;
  };
  UserName: string;
  WorkflowName: string;
  PreviousState: {
    DisplayName: string;
    StateID: string;
  };
}

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method not allowed' });
  }

  try {
    const payload: WorkflowPayload = req.body;

    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',
    });
  }
}
`}
</Code>

### 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.

Workflow Email in Sitecore XM Cloud Using Webhook Submit Actions


In today’s digital world, businesses are increasingly leveraging location-based data to enhance user experiences. Whether it’s helping customers find nearby stores or delivering personalized content based on a user’s geographical location, geospatial search plays a pivotal role in providing relevant results. Sitecore's robust search features allow for seamless integration of geospatial capabilities, making it easier than ever to implement geospatial search in your digital solutions.

## 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.

![image](/images/post/search-field.png)

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:

<Code language="json">
{`{
    "document": {
        "id": "1DrJohnDoe",
        "fields": {
            "name": "Dr. John Doe",
            "description": "Lorem ipsum sit a dor, lorem ipsum sit a dor, lorem ipsum",
            "type": "doctor",
            "coordinates": "40.7127837,-74.0059413"
        }
    }
}`}
</Code>

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:

<Code language="tsx">
{`useSearchResults<ArticleModel, InitialState>({
  query: (query): any => {
    const latitude = 40.2404; // User's latitude
    const longitude = -75.1652; // User's longitude
    const radius = '100km'; // Search radius (100 km)
    const sourceId = '000000'; // Source ID of PUSH API

    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]);
    }
  }
});`}
</Code>


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.



Unlocking the Power of Geospatial in Sitecore Search


When configuring a Sitecore instance for a production environment, performance optimization is critical to ensure smooth operation under heavy traffic and usage. As a Sitecore developer, I often configure the settings below to enhance performance, particularly for high-demand sites. These settings are designed to manage memory usage, reduce unnecessary resource consumption, and fine-tune how Sitecore handles tasks like caching, analytics, and content management. By adjusting cache sizes, disabling certain features, and refining other key configurations, we can ensure that Sitecore performs efficiently while balancing resource utilization.

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.



<Code language="xml">
{`<?xml version="1.0"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:set="http://www.sitecore.net/xmlconfig/set/" xmlns:env="http://www.sitecore.net/xmlconfig/env/" xmlns:role="http://www.sitecore.net/xmlconfig/role/">
    <sitecore>

        <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>`}
</Code>

## 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.

Sitecore Performance Optimization Configuration


In this blog post, we will explore a common requirement in Sitecore Headless SXA, exposing site-specific settings and global data to the front end when working with a JSS headless site.

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

<Code language="typescript">
{`export type SitecorePageProps = {
  site: SiteInfo;
  locale: string;
  dictionary: DictionaryPhrases;
  componentProps: ComponentPropsCollection;
  notFound: boolean;
  layoutData: LayoutServiceData;
  headLinks: HTMLLink[];
  SiteConfigurations: SiteSettingFields;
};`}
</Code>

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`.

<Code language="jsx">
{`import { GraphQLClient } from '@sitecore-jss/sitecore-jss';
import { debug, GraphQLLayoutService, GraphQLLayoutServiceConfig, LayoutServiceData } from '@sitecore-jss/sitecore-jss-nextjs';

export class GraphQLSettingsService extends GraphQLLayoutService {
  private myGraphQLClient: GraphQLClient;

  constructor(public serviceConfig: GraphQLLayoutServiceConfig) {
    super(serviceConfig);
    this.myGraphQLClient = this.getGraphQLClient();
  }

  public async fetchSettings(siteName: string, language: string): Promise<LayoutServiceData> {
    const query = this.getQuery(siteName, language);
    
    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
                }
              }
            }
          }
        }
      }
    }\`;
  }
}`}
</Code>

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

<Code language="typescript">
{`import { GetStaticPropsContext, GetServerSidePropsContext } from 'next';
import config from 'temp/config';
import { Plugin } from '..';
import { GraphQLSettingsService } from '../services/settings-service';
import { SitecorePageProps } from 'lib/page-props';
import clientFactory from 'lib/graphql-client-factory';

class GetSiteSettingsPlugin implements Plugin {
  private settingsRequestClient: GraphQLSettingsService;

  constructor() {
    const siteName = config.sitecoreSiteName;
    this.settingsRequestClient = new GraphQLSettingsService({
      siteName,
      clientFactory,
      retries: (process.env.GRAPH_QL_SERVICE_RETRIES && parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) as number,
    });
  }

  order = 2;

  async exec(props: SitecorePageProps, context: GetServerSidePropsContext | GetStaticPropsContext) {
    const siteSettings = await this.settingsRequestClient.fetchSettings(
      props?.site?.name,
      props.locale
    );

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

    return props;
  }
}

export const getSiteSettingsPlugin = new GetSiteSettingsPlugin();`}
</Code>

### 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!

Exposing Site Settings from the Settings item in a Headless JSS Next.js Application


Recently, while working with a Sitecore 10.4 deployment in an Azure environment, we encountered an interesting challenge: handling Sitecore Content Management (CM) and IdentityServer (SI) behind a proxy/CDN setup using Azure Application Gateway. The DNS configuration was managed at the Application Gateway level. Here’s how we resolved the issue.

### 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.

![image](/images/post/sc-si-auth-error.png)

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

<Code language="xml">
{`<AllowedCorsOrigins>
  <AllowedCorsOriginsGroup1>https://cm.xyz.com|https://cm.cdn.xyz.com</AllowedCorsOriginsGroup1>
</AllowedCorsOrigins>`}
</Code>

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

<Code language="xml">
{`<system.webServer>
  <rewrite>
    <outboundRules>
      <rule name="HttpToHttpsOutbound" preCondition="IsRedirect">
        <match serverVariable="RESPONSE_Location" pattern="^http://cm.xyz.com/(.*)" />
        <action type="Rewrite" value="https://cm.cdn.xyz.com/{R:1}" />
      </rule>
      <preConditions>
        <preCondition name="IsRedirect">
          <add input="{RESPONSE_STATUS}" pattern="3\d\d" />
        </preCondition>
      </preConditions>
    </outboundRules>
  </rewrite>
</system.webServer>`}
</Code>

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.

Handling Sitecore CM and IdentityServer Behind a Proxy or CDN in an Azure Environment


In the composable world of modern Sitecore solutions, integrating search appliances like Coveo with digital asset management tools such as Sitecore Content Hub is common practice. One typical use case involves building Coveo search sources to index content stored in Sitecore Content Hub. These indexes can then be used to create rich front-end search experiences.


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

```http
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:

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

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

```json
{
    "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**:
     ```http
     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.
   ```json
   {
       "addOrUpdate": [
           {
               "m_title": "Example Title",
               "m_overview": "Description",
               "documentId": "http://example.com",
               "data": "Content",
               "fileExtension": ".txt"
           }
       ]
   }
   ```

2. **Upload Data**:
   - **PUT Request**:
     ```http
     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**:
     ```http
     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#:

<Code language="c#">
{`public void Process(string apiUrl, bool recursive = true)
{
    // Calling scroll API, and parse the API response into relevant model
    var contentHubItems = GetContentHubAssets(apiUrl);

    // 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);
    }
}`}
</Code>

### 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. 

Indexing Sitecore Content Hub Assets in Coveo: A Practical Guide


The Sitecore Search SDK Starter Kit provides a powerful foundation for developers to build robust and user-friendly search functionalities into their websites. This open-source project offers a significant advantage by streamlining the integration of Sitecore Search with React based applications. Recently, I have made few enhancements to the forked GitHub repository (https://github.com/Sitecore/Sitecore-Search-JS-SDK-Starter-Kit) that aim to improve the overall search experience for end users and provide developers with a more efficient development workflow.


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

![image](/images/post/starter-kit-enhancements/modular-approach.png)

#### 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.

![image](/images/post/starter-kit-enhancements/facets-improvement.png)


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.

<Code language="tsx">
{`import { CheckIcon } from '@radix-ui/react-icons';
import type { SearchResponseFacet } from '@sitecore-search/react';
import { AccordionFacets } from '@sitecore-search/ui';
import { useEffect, useState } from 'react';
import type { SelectedFacets } from '../Facets';
import { AccordionFacetsStyled } from '../styled';
export interface FacetListType {
  facet: SearchResponseFacet;
  selectedFacetsToRender: SelectedFacets[];
  facetsnumbertoshow: number;
}

export const FacetList = ({ selectedFacetsToRender, facet, facetsnumbertoshow }: FacetListType) => {
  const isSelected = (facetID: string, facetValue: string) => {
    return (
      selectedFacetsToRender.filter(
        (x) => x.id === facetID && x.values.map((q) => q.id).includes(facetValue)
      ).length > 0
    );
  };

  const minNumberOfItemsToShow = facetsnumbertoshow ?? 5;
  const totalItems = facet.value.length;
  const [keyword, setKeyword] = useState('');
  const [filteredItems, setFilteredItems] = useState(facet.value);
  const [numberOfItemsToShow, setNumberOfItemsToShow] = useState(minNumberOfItemsToShow);

  useEffect(() => {
    // This will be called whenever parentProp changes (i.e., when the parent component rerenders)
    setFilteredItems(facet.value);
  }, [facet.value]);

  const handleInputChange = (event: { target: { value: string } }) => {
    const inputKeyword = event.target.value.toLowerCase();
    setKeyword(inputKeyword);

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

  const handleShowMore = () => {
    setNumberOfItemsToShow((prevVisibleItems) => prevVisibleItems + minNumberOfItemsToShow);
  };

  const handleShowLess = () => {
    setNumberOfItemsToShow((prevVisibleItems) =>
      Math.max(prevVisibleItems - minNumberOfItemsToShow, minNumberOfItemsToShow)
    );
  };

  return (
    <>
      <AccordionFacetsStyled.Facet facetId={facet.name} key={facet.name}>
        <AccordionFacets.Content>
          <div className="input_wrap">
            <input
              name={facet.name}
              placeholder="Type to filter..."
              id={facet.name}
              type="text"
              value={keyword}
              onChange={handleInputChange}
            />
          </div>
          <AccordionFacetsStyled.ValueList>
            {filteredItems.slice(0, numberOfItemsToShow).map((v, index) => (
              ...
            ))}
          </AccordionFacetsStyled.ValueList>

          {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;`}
</Code>

### 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.

![image](/images/post/starter-kit-enhancements/searh-query.png)

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

<Code language="tsx">
{`const updateFacetsSearchParams = (params: any, remove = false) => {
    const queryParams = new URLSearchParams(location.search);
    const searchParamsObject = paramsToObject(queryParams.entries()) as any;
    let values = searchParamsObject[params.facetId]?.split(',') ?? [];
    values = values.filter((n: any) => n);
    if (remove || params.checked === false) {
      const index = values.indexOf(params.facetValueId);
      if (index > -1) {
        values.splice(index, 1);
      }
    } else {
      values.push(params.facetValueId);
    }
    if (values.length <= 0) {
      delete searchParamsObject[params.facetId];
    }
    delete searchParamsObject.page;
    searchParamsObject[params.facetId] = removeDuplicates(values).join(',');
    const updatedRelativeUrl = generateQueryString('/search', searchParamsObject);
    navigate(updatedRelativeUrl);
  };`}

</Code>

### 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.


Sitecore Search SDK Starter Kit: Enhanced User Experience


In this blog post, I'll walk you through the process of smoothly leveraging the Search SDK Starter Kit into a Sitecore Next.js solution.

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

<Code language="jsx">
{`npm install --save @sitecore-search/react
npm install --save @sitecore-search/ui
npm install --save styled-components`}
</Code>

### Configuration Steps

#### 1. Create Source in CEC

Follow the steps outlined in the [official documentation](https://doc.sitecore.com/search/en/users/search-user-guide/configuring-a-source.html) 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](https://doc.sitecore.com/search/en/users/search-user-guide/create-auto-complete-functionality-using-suggestions-blocks.html) for configuration details.

#### 3. Setup Sorting Options

Configure sorting options to include `featured_desc` and `featured_asc` criteria as per the [documentation](https://doc.sitecore.com/search/en/users/search-user-guide/walkthrough--adding-the-option-to-sort-by-top-views.html).

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

![image](/images/post/starter-kit/sk-1.jpg)

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.

![image](/images/post/starter-kit/sk-2.jpg)

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`

![image](/images/post/starter-kit/sk-3.jpg)

5. Create environment variables in the `.env` file:
   
<Code language="dotenv">
{`NEXT_PUBLIC_SEARCH_CUSTOMER_KEY=<customer-key>
NEXT_PUBLIC_SEARCH_API_KEY=<api-key>
NEXT_PUBLIC_SEARCH_ENV=prod`}
</Code>

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

Add necessary imports.

<Code language='tsx'>
{`import { LanguageContext } from 'src/contexts/languageContext';
import useLanguage from 'src/hooks/useLanguage';`}
</Code>

add following const in within the main function.
<Code language='tsx'>
{`const { language, setLanguage } = useLanguage();`}
</Code>


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:

<Code language="jsx">
{`<LanguageContext.Provider value={{ language, setLanguage }}> 
  <WidgetsProvider 
    env={process.env.NEXT_PUBLIC_SEARCH_ENV as Environment} 
    customerKey={process.env.NEXT_PUBLIC_SEARCH_CUSTOMER_KEY} 
    apiKey={process.env.NEXT_PUBLIC_SEARCH_API_KEY} 
    publicSuffix={true}>
      <I18nProvider lngDict={dictionary} locale={pageProps.locale}> </I18nProvider> 
  </WidgetsProvider> 
</LanguageContext.Provider>`}
</Code>


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:

<Code language="jsx">
{`import withPageTracking from 'src/hocs/withPageTracking';
import SearchResults from 'src/widgets/SearchResults';

const Search = (): JSX.Element => {
  return <SearchResults key={'search'} rfkId="rfkid_7" defaultKeyphrase={''} />;
};

export default withPageTracking(Search);`}
</Code>

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.

![image](/images/post/starter-kit/sk-5.jpg)

## 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.






Leveraging Sitecore Search SDK Starter Kit into Your Sitecore Next.js Solution [Part 2]


Moving to a new Coveo Cloud organization can be a strategic step for your business. But what about the customizations and data you've built up in your dev or QA organization? This post will guide you through the process of migrating changes between Coveo cloud organizations.

### 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.

![image](/images/post/coveo-create-snapshot.png)

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

![image](/images/post/coveo-add-resources-to-snapshot.png)

#### 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.

Coveo for Sitecore - Guide to Migrate Changes Between Cloud Organizations


In today's web development landscape, delivering efficient and intuitive search functionality is crucial to provide an enhanced user experience for your visitors. With the advent of Sitecore Search, developers now have a powerful tool at their disposal to seamlessly integrate robust search capabilities into their Next.js applications.

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.
<Code language="jsx">
{`npm install --save @sitecore-search/react
npm install --save @sitecore-search/ui	`}
</Code>
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.

<Code language="jsx">
{`<WidgetsProvider
			env={process.env.NEXT_PUBLIC_SEARCH_ENV as any}
			customerKey={process.env.NEXT_PUBLIC_SEARCH_CUSTOMER_KEY}
			apiKey={process.env.NEXT_PUBLIC_SEARCH_API_KEY}
			publicSuffix={true}>
	<Component  {...rest}  />
</WidgetsProvider> `}
</Code>
3. Configure the Search Config object to establish the connection between the application and the designated search instance. It's recommended to store sensitive information, such as API keys, in environment variables for security purposes.

<Code language="JSX">
{`NEXT_PUBLIC_SEARCH_CUSTOMER_KEY=<customer-key>
NEXT_PUBLIC_SEARCH_API_KEY=<api-key>
NEXT_PUBLIC_SEARCH_ENV=prod`}
</Code>
### Building Search Functionality with the React SDK

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

<Code language="jsx">
{`import type { SearchResultsInitialState, SearchResultsStoreState, SearchResultsWidgetQuery } from '@sitecore-search/react';
import { WidgetDataType, useSearchResults, useSearchResultsSelectedFacets, widget } from '@sitecore-search/react';

type ArticleModel = {
  id: string;
  type?: string;
  title?: string;
  name?: string;
  subtitle?: string;
  url?: string;
  description?: string;
  content_text?: string;
  image_url?: string;
  source_id?: string;
};

type ArticleSearchResultsProps = {
  defaultSortType?: SearchResultsStoreState['sortType'];
  defaultPage?: SearchResultsStoreState['page'];
  defaultItemsPerPage?: SearchResultsStoreState['itemsPerPage'];
  defaultKeyphrase?: SearchResultsStoreState['keyphrase'];
};

type InitialState = SearchResultsInitialState<'itemsPerPage' | 'keyphrase' | 'page' | 'sortType'>;

export const SearchResultsComponent = ({
  defaultSortType = 'date_desc',
  defaultPage = 1,
  defaultKeyphrase = '',
  defaultItemsPerPage = 10,
}: ArticleSearchResultsProps) => {
  const {
    widgetRef,
    actions: {
      onResultsPerPageChange,
      onPageNumberChange,
      onItemClick,
      onFilterClick,
      onSortChange,
      onFacetClick,
      onClearFilters,
    },
    state: { sortType, page, itemsPerPage },
    queryResult: {
      isLoading,
      isFetching,
      data: {
        total_item: totalItems = 0,
        sort: { choices: sortChoices = [] } = {},
        facet: facets = [],
        content: articles = [],
      } = {},
    },
  } = useSearchResults<ArticleModel, InitialState>({
    query: (query:SearchResultsWidgetQuery) => query,
    state: {
      sortType: defaultSortType,
      page: defaultPage,
      itemsPerPage: defaultItemsPerPage,
      keyphrase: defaultKeyphrase,
    },
  });
  const totalPages = Math.ceil(totalItems / itemsPerPage);
  const selectedSortIndex = sortChoices.findIndex((s:any) => s.name === sortType);
  const selectedFacetsFromApi = useSearchResultsSelectedFacets();
  if (isLoading) {
    return ( <div> ... </div> );
  }
  return ( <div ref={widgetRef}> ... </div> );
};

const SearchResultsStyledWidget = widget(SearchResultsComponent, WidgetDataType.SEARCH_RESULTS, 'content');

export default SearchResultsStyledWidget;
`}
</Code>

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](https://github.com/Sitecore/Sitecore-Search-JS-SDK-Starter-Kit) to our Sitecore Next.js solution. Stay tuned for simple steps to create a great search experience!

Sitecore Search SDK Integration [Part 1]


SharePoint On-Premises remains a cornerstone of many organizations' collaboration and content management strategies. Among its key features are WebParts, which allow users to customize SharePoint sites with various functionalities. However, managing WebParts in SharePoint On-Premises environments can be complex, especially across multiple farms or servers. Fortunately, PowerShell offers a robust set of tools to streamline the process. In this blog post, we'll explore how PowerShell can simplify the installation, updating, and uninstallation of SharePoint On-Premises WebParts, empowering administrators to efficiently manage their SharePoint deployments.

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:

<Code language="PowerShell">
{`Add-SPSolution "C:\Path\To\WebPart\File.wsp"
Install-SPSolution -Identity WebPartName.wsp –WebApplication <web application url> -GACDeployment
`}
</Code>

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:

<Code language="PowerShell">
{`Update-SPSolution -Identity WebPartName.wsp -LiteralPath "C:\Path\To\Updated\WebPart\File.wsp" -GACDeployment
`}
</Code>

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:

<Code language="PowerShell">
{`Uninstall-SPSolution -Identity WebPartName.wsp 
Remove-SPSolution -Identity WebPartName.wsp 
`}
</Code>

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.

Showing posts fromsitecoreai

Agentic Studio 101 for Developers — Where Agents Stop and Your Code Still Matters

SitecoreAI After XM Cloud — What Actually Changes for a Next.js Implementation Team