Experience Sitecore !

If you've ever worked on multiple SitecoreAI (XM Cloud) projects at the same time, you know the pain. Often you have to terminate working on Project A, run docker compose down, wait, switch .env files, run docker compose up, wait some more... and then realize you need to quickly check something back in Project A. Rinse, repeat, lose your sanity. What a time waste!

What if I told you there's a way to run three completely independent XM Cloud Docker environments side by side, all on the same Windows machine, all accessible on standard HTTPS port 443, with full network isolation between for each of them?

Let's dig into how I made it work.

The Problem - Why Can't We Just Run Three Docker Compose Stacks?

At first glance, running three copies of the XM Cloud starter kit seems straightforward. Clone the repo three times, change some ports, and done. Right?

Not quite. There are two showstoppers:

1. The Hostname Lock-In

Sitecore's XM Cloud identity server (Auth0) expects callbacks to xmcloudcm.localhost or *.xmcloudcm.localhost. This is hardcoded on their end. Every single CM instance in the standard setup uses xmcloudcm.localhost as its hostname. If three CM containers all claim the same hostname, only one wins.

2. The Traefik Port War

Each codebase ships with its own Traefik reverse proxy, and all of them want port 443 and port 8079. Docker will happily start the first one and reject the rest due to a port conflict.

And there are secondary conflicts too - MSSQL (port 14330) and Solr (port 8984) also collide.

The Solution - A Shared Traefik Gateway with Subdomain Routing

The architecture I landed on is built around three key ideas:

One Traefik to rule them all. Instead of three competing Traefik instances, we run a single shared Traefik at the root level that acts as the gateway for all environments.

Third-level subdomains for CM. Since Auth0 accepts *.xmcloudcm.localhost, we use one.xmcloudcm.localhost, two.xmcloudcm.localhost, and three.xmcloudcm.localhost. One wildcard TLS certificate covers all three, and the codebases configured as below:

  ┌────────────┬─────────────────────────────────────────────┬────────────┬───────────┐
  │  Codebase  │                 CM Hostname                 │ MSSQL Port │ Solr Port │
  ├────────────┼─────────────────────────────────────────────┼────────────┼───────────┤
  │ codebase-1 │ https://one.xmcloudcm.localhost/sitecore/   │ 14331      │ 8984      │
  ├────────────┼─────────────────────────────────────────────┼────────────┼───────────┤
  │ codebase-2 │ https://two.xmcloudcm.localhost/sitecore/   │ 14332      │ 8985      │
  ├────────────┼─────────────────────────────────────────────┼────────────┼───────────┤
  │ codebase-3 │ https://three.xmcloudcm.localhost/sitecore/ │ 14333      │ 8986      │
  └────────────┴─────────────────────────────────────────────┴────────────┴───────────┘

A shared bridge network for Traefik routing. CM and rendering containers from each codebase join a shared nat network so Traefik can reach them, while internal infrastructure (MSSQL, Solr) stays isolated on each project's default network.

Here's the high-level picture:

                     +----------------------+
                     |   Shared Traefik     |
                     |   Port 443 / 8079    |
                     +--+-------+-------+---+
                        |       |       |
                   traefik-shared (nat network)
                        |       |       |
   +----------+--+  +---+------+---+  +--+----------+
   | codebase-1  |  | codebase-2   |  | codebase-3  |
   |  xmc-one    |  |  xmc-two     |  |  xmc-three  |
   | MSSQL:14331 |  | MSSQL:14332  |  | MSSQL:14333 |
   | Solr:8984   |  | Solr:8985    |  | Solr:8986   |
   +-------------+  +--------------+  +-------------+

And the hostname mapping should loke as:

  ┌─────────────┬─────────────────────────────────────────────┐
  │   Service   │                  Hostname                   │
  ├─────────────┼─────────────────────────────────────────────┤
  │ CM 1        │ https://one.xmcloudcm.localhost/sitecore/   │
  ├─────────────┼─────────────────────────────────────────────┤
  │ CM 2        │ https://two.xmcloudcm.localhost/sitecore/   │
  ├─────────────┼─────────────────────────────────────────────┤
  │ CM 3        │ https://three.xmcloudcm.localhost/sitecore/ │
  ├─────────────┼─────────────────────────────────────────────┤
  │ Rendering 1 │ https://nextjs.xmc-one.localhost/           │
  ├─────────────┼─────────────────────────────────────────────┤
  │ Rendering 2 │ https://nextjs.xmc-two.localhost/           │
  ├─────────────┼─────────────────────────────────────────────┤
  │ Rendering 3 │ https://nextjs.xmc-three.localhost/         │
  └─────────────┴─────────────────────────────────────────────┘

What We Need to Change

The beauty of this solution is how little needs to change. Let me walk through every modification.

Step 1: The Shared Traefik

Create a shared-traefik folder at the root of your multi-docker directory. It gets its own docker-compose.yml:

services:
  traefik:
    isolation: hyperv
    image: traefik:v3.6.4-windowsservercore-ltsc2022
    command:
      - "--ping"
      - "--api.insecure=true"
      - "--providers.docker.endpoint=npipe:////./pipe/docker_engine"
      - "--providers.docker.exposedByDefault=false"
      - "--providers.file.directory=C:/etc/traefik/config/dynamic"
      - "--entryPoints.websecure.address=:443"
      - "--entryPoints.websecure.forwardedHeaders.insecure"
    ports:
      - "443:443"
      - "8079:8080"
    healthcheck:
      test: ["CMD", "traefik", "healthcheck", "--ping"]
    volumes:
      - source: \\.\pipe\docker_engine\
        target: \\.\pipe\docker_engine\
        type: npipe
      - ./traefik:C:/etc/traefik
    networks:
      - traefik-shared

networks:
  traefik-shared:
    name: traefik-shared
    external: true

The key insight here: a single Traefik connects to the Docker engine via a Windows named pipe, enabling it to discover all containers across all Compose projects. It joins the traefik-shared network to actually reach the CM and rendering containers.

Before starting Traefik, create the shared network with the Windows nat driver:

docker network create -d nat traefik-shared

Why nat and not bridge? Windows containers don't support the bridge driver. If you try docker network create traefik-shared without -d nat, you'll get: "could not find plugin bridge in v1 plugin registry". This was one of the first gotchas I ran into.

The TLS config (shared-traefik/traefik/config/dynamic/certs_config.yaml) references wildcard certificates:

tls:
  certificates:
    - certFile: C:\etc\traefik\certs\_wildcard.xmcloudcm.localhost.pem
      keyFile: C:\etc\traefik\certs\_wildcard.xmcloudcm.localhost-key.pem
    - certFile: C:\etc\traefik\certs\_wildcard.xmc-one.localhost.pem
      keyFile: C:\etc\traefik\certs\_wildcard.xmc-one.localhost-key.pem
    - certFile: C:\etc\traefik\certs\_wildcard.xmc-two.localhost.pem
      keyFile: C:\etc\traefik\certs\_wildcard.xmc-two.localhost-key.pem
    - certFile: C:\etc\traefik\certs\_wildcard.xmc-three.localhost.pem
      keyFile: C:\etc\traefik\certs\_wildcard.xmc-three.localhost-key.pem

Step 2: Parameterize the Traefik Labels

This is the most important change to the existing codebase, and also the most subtle.

When Traefik uses the Docker provider, it reads labels from containers to build its routing table. In the stock docker-compose.yml, the CM service has labels like:

- "traefik.http.routers.cm-secure.rule=Host(`${CM_HOST}`)"

The router name cm-secure is hardcoded. If three CM containers all define cm-secure, Traefik merges them into a single router with unpredictable results.

The fix is elegant: prefix every router, middleware, and service name with ${COMPOSE_PROJECT_NAME}:

- "traefik.http.routers.${COMPOSE_PROJECT_NAME}-cm-secure.rule=Host(`${CM_HOST}`)"

Since each codebase has a unique COMPOSE_PROJECT_NAME in its .env (e.g., xmc-one, xmc-two, xmc-three), the router names become xmc-one-cm-secure, xmc-two-cm-secure, etc. Globally unique. Zero conflicts.

This same change applies to all Traefik label lines in both docker-compose.yml (CM labels) and docker-compose.override.yml (rendering host labels).

I also parameterized the MSSQL and Solr host ports while I was in there:

# Was: "14330:1433"
ports:
  - "${MSSQL_PORT:-14330}:1433"

The :-14330 default means if you don't set MSSQL_PORT, nothing changes. Backward compatible.

Step 3: The Multi-Instance Override

Each codebase gets a docker-compose.multi.yml that does three things:

1. Disables the per-codebase Traefik (since the shared one handles everything)
2. Connects CM and rendering to the shared Traefik network
3. Passes the site name to the rendering container

services:
  traefik:
    deploy:
      replicas: 0

  cm:
    labels:
      - "traefik.docker.network=traefik-shared"
    networks:
      - default
      - traefik-shared

  rendering-nextjs:
    environment:
      NEXT_PUBLIC_DEFAULT_SITE_NAME: ${SITE_NAME:-xmc-one}
    labels:
      - "traefik.docker.network=traefik-shared"
    networks:
      - default
      - traefik-shared

networks:
  traefik-shared:
    name: traefik-shared
    external: true

The traefik.docker.network label is critical - it tells the shared Traefik which network to use when routing to this container. Without it, Traefik might try to route via the wrong network and fail silently.

This file is loaded automatically via the COMPOSE_FILE variable in .env:

COMPOSE_FILE=docker-compose.yml;docker-compose.override.yml;docker-compose.multi.yml

Windows gotcha: The COMPOSE_FILE separator on Windows is ; (semicolon), not : (colon). Using colons causes a cryptic CreateFile ... The filename, directory name, or volume label syntax is incorrect error. This one took me longer to figure out than I'd like to admit.

Step 4: Per-Codebase .env Configuration

Each codebase's .env gets a handful of unique values:

Don't forget SITECORE_FedAuth_dot_Auth0_dot_RedirectBaseUrl - it must match the CM hostname, for example:

SITECORE_FedAuth_dot_Auth0_dot_RedirectBaseUrl=https://one.xmcloudcm.localhost/

Step 5: The Hosts File

This is pretty simple - just add these entries to C:\Windows\System32\drivers\etc\hosts:

127.0.0.1	one.xmcloudcm.localhost
127.0.0.1	two.xmcloudcm.localhost
127.0.0.1	three.xmcloudcm.localhost
127.0.0.1	nextjs.xmc-one.localhost
127.0.0.1	nextjs.xmc-two.localhost
127.0.0.1	nextjs.xmc-three.localhost

Step 6: Fix up.ps1

The up.ps1 script has a Traefik health check that uses the hardcoded router name cm-secure@docker. Since we parameterized it, we need to read COMPOSE_PROJECT_NAME and use it:

$composeProjectName = ($envContent | Where-Object {
    $_ -imatch "^COMPOSE_PROJECT_NAME=.+"
}).Split("=")[1]

# Updated health check
$status = Invoke-RestMethod "http://localhost:8079/api/http/routers/$composeProjectName-cm-secure@docker"

And the hardcoded Start-Process https://xmcloudcm.localhost/sitecore/ becomes:

Start-Process "https://$xmCloudHost/sitecore/"

Making the Next.js Rendering Hosts Work

Getting the CM to respond on a subdomain turned out to be the easy part. Wiring up the Next.js rendering hosts - that's where the real fun began.

The "Configuration error" Wall

After the CM instances were humming along on their subdomains, I turned my attention to the rendering hosts. Each codebase's rendering-nextjs container mounts the Next.js app from examples/basic-nextjs and runs npm install && npm run dev as its entrypoint. Simple enough. Except all three containers immediately crashed with:

Error: Configuration error: provide either Edge contextId or
local credentials (api.local.apiHost + api.local.apiKey).

The issue? The stock sitecore.config.ts ships as a bare defineConfig({{}}) - no API configuration at all. This works when you're connecting to XM Cloud Edge in production, but in local Docker mode, the Content SDK's build tools need to know where the CM lives.

The fix is to add the api.local block:

import { defineConfig } from '@sitecore-content-sdk/nextjs/config';

export default defineConfig({
  api: {
    local: {
      apiKey: process.env.SITECORE_API_KEY || '',
      apiHost: process.env.SITECORE_API_HOST || '',
    },
  },
  defaultSite: process.env.NEXT_PUBLIC_DEFAULT_SITE_NAME || 'xmc-one',
  defaultLanguage: 'en',
});

The SITECORE_API_HOST is set to http://cm by the compose override (the internal Docker DNS name for the CM container), and SITECORE_API_KEY comes from the .env file. So far so good.

The "Invalid API Key" Surprise

With the config in place, I restarted the rendering containers. They got further this time - the SDK successfully connected to the CM - but then:

ClientError: Provided SSC API keyData is not valid.

Here's the thing about Sitecore API keys: having a GUID in your .env file isn't enough. That GUID must be registered as an item inside Sitecore's content tree at /sitecore/system/Settings/Services/API Keys/. Without it, Sitecore rejects the key outright.

The standard up.ps1 flow handles this via the Sitecore CLI's serialization push, but since we're running three parallel instances, we need to do it for each:

cd codebase-1
dotnet sitecore cloud login                    # Browser auth required
dotnet sitecore connect --ref xmcloud `
  --cm https://one.xmcloudcm.localhost `
  --allow-write true -n default

& ./local-containers/docker/build/cm/templates/import-templates.ps1 `
  -RenderingSiteName 'xmc-one' `
  -SitecoreApiKey 'c46d10a5-9d62-4aa9-a83d-3e20a34bc981'

This creates the API key item under /sitecore/system/Settings/Services/API Keys/xmc-one with CORS and controller access set to *. The browser login is interactive (Auth0 device flow), but you only need to do it once per codebase.

The "//en" Path Mismatch Mystery

After registering the API keys and restarting the containers, the rendering hosts started successfully. Next.js reported Ready in 6.2s. I opened https://nextjs.xmc-one.localhost/ in the browser, and... "Page not found."

The container logs told the story:

[Error: Requested and resolved page mismatch: //en /en]
GET / 404 in 53ms

That double slash in //en was the clue. The Content SDK's multisite and locale middleware were fighting over path resolution. The locale middleware was adding /en to the path /, but without a defaultSite configured, the multisite resolver was confused about which site to use, producing a mangled double-slash path.

Two changes fixed it:

1. Set defaultSite in sitecore.config.ts (shown above) - this tells the SDK which Sitecore site to resolve by default
2. Pass NEXT_PUBLIC_DEFAULT_SITE_NAME as an environment variable to the rendering container via docker-compose.multi.yml

The Hostname Binding

Even with the path mismatch fixed, the rendering host still returned 404. The CM's layout service was responding correctly when queried directly - I verified this with:

curl -sk "https://one.xmcloudcm.localhost/sitecore/api/layout/render/jss?item=/&sc_apikey=&sc_site=xmc-one&sc_lang=en"

That returned valid JSON with the Home page route data. So the CM was fine. The problem was in Sitecore's site resolution.

In the Sitecore Content Editor, each site has a Site Grouping item with a Hostname field. This field tells Sitecore which incoming hostname maps to which site. Without it, when the rendering host queries the CM for layout data, Sitecore doesn't know which site the request is for.

The fix: go to each CM's Content Editor and set the Hostname to the rendering host's domain:

• xmc-one site -> Hostname: nextjs.xmc-one.localhost
• xmc-two site -> Hostname: nextjs.xmc-two.localhost
• xmc-three site -> Hostname: nextjs.xmc-three.localhost

After that, all three rendering hosts returned HTTP 200, each serving content from their respective Sitecore instance. Three independent XM Cloud stacks, all running in parallel, all on standard HTTPS.

Running It All

First-Time Setup

# Run as Administrator
cd C:\Projects\SHIFT-AI\Multiple-Docker
.\setup-multi.ps1

This creates the Docker network, generates wildcard TLS certificates with mkcert, and updates the hosts file.

Then initialize each codebase (if not already done):

cd codebase-1\local-containers\scripts
.\init.ps1 -InitEnv -LicenseXmlPath C:\License\license.xml -AdminPassword "YourPassword"
# Repeat for codebase-2 and codebase-3

Daily Usage

# Start everything
.\start-all.ps1

# Start just one codebase
.\start-all.ps1 -Codebases @("codebase-2")

# Stop everything
.\stop-all.ps1

# Stop codebases but keep Traefik running (faster restarts)
.\stop-all.ps1 -KeepTraefik

Post-Startup: Register API Keys and Create Sites

After the CMs are healthy, you need to register the API keys and create sites with hostname bindings (see the sections above). This is a one-time step per codebase.

Verifying It Works

Check the Traefik Dashboard

Open http://localhost:8079/dashboard/. You should see six routers - two per codebase (CM + rendering), each with its unique name prefix.

Hit Each CM Instance

• https://one.xmcloudcm.localhost/sitecore/ -> Auth0 login redirect
• https://two.xmcloudcm.localhost/sitecore/ -> Auth0 login redirect
• https://three.xmcloudcm.localhost/sitecore/ -> Auth0 login redirect

Hit Each Rendering Host

• https://nextjs.xmc-one.localhost/ -> Site home page (HTTP 200)
• https://nextjs.xmc-two.localhost/ -> Site home page (HTTP 200)
• https://nextjs.xmc-three.localhost/ -> Site home page (HTTP 200)

All three should serve their respective Sitecore site content, each powered by an independent CM, MSSQL, and Solr instance.

Lessons Learned

Windows Docker networking has its own rules. Networks must use nat. A container can't reliably join multiple nat networks. I originally designed three separate Traefik networks for strict isolation but had to collapse them into one shared nat network. In practice, only CM and rendering containers join the shared network - MSSQL and Solr stay isolated on their project-default networks.

COMPOSE_FILE uses semicolons on Windows. The Linux docs show COMPOSE_FILE=a.yml:b.yml:c.yml. On Windows, it's a.yml;b.yml;c.yml. Using colons produces a cryptic CreateFile ... volume label syntax error that doesn't immediately suggest a separator issue.

Traefik label naming is global. This was the non-obvious gotcha. When Traefik uses the Docker provider, router names are global across all containers it discovers. Two containers defining the same router name creates a conflict that Traefik resolves silently (and wrongly). Prefixing with ${COMPOSE_PROJECT_NAME} is a pattern I'll use in every multi-project Docker setup from now on.

Docker Compose labels merge, they don't replace. When you override a service in a compose override file, labels from the base file persist. You can add new labels but can't remove old ones. This is why the parameterization approach (changing the base file) is cleaner than trying to override labels.

sitecore.config.ts needs explicit local API config. The stock defineConfig({{}}) assumes Edge mode. For local Docker development, you must specify api.local.apiKey and api.local.apiHost. The Content SDK's build tools (sitecore-tools project build) fail at startup without them.

defaultSite prevents the //en path mismatch. Without it, the multisite and locale middlewares can't agree on path resolution, producing //en instead of /en. This manifests as every page returning 404 even though the CM has valid content. Setting defaultSite in the config and passing NEXT_PUBLIC_DEFAULT_SITE_NAME as an environment variable resolved this instantly.

API keys must be registered in Sitecore, not just in .env. Having a GUID in SITECORE_API_KEY_APP_STARTER is necessary but not sufficient. The GUID must exist as a Sitecore item under /sitecore/system/Settings/Services/API Keys/. The import-templates.ps1 script + dotnet sitecore ser push handles this.

Sitecore sites need hostname bindings. Even with correct API keys and config, the rendering host gets 404 until the site's Hostname field in Sitecore matches the rendering host's domain. The CM's layout service uses this to resolve which site a request belongs to.

What Could Be Simplified Further

• Template-driven .env generation: A script that generates .env files for N codebases, not just three.
• Compose profiles: Instead of deploy.replicas: 0, use Docker Compose profiles to toggle between standalone and multi-instance modes.
• Single-codebase fallback: Remove the COMPOSE_FILE line from .env to revert any codebase to standalone mode instantly.
• Automated API key registration: A script that generates, registers, and configures the API key for each codebase in one step.

The total delta is about 10 lines changed per codebase in the Docker compose files, a sitecore.config.ts update, and a handful of new infrastructure files at the root. Not bad for what felt like an impossible requirement.

If you've been juggling multiple XM Cloud projects and constantly stopping and starting Docker environments, I hope this saves you some time and frustration. Drop a comment if you've found other approaches or run into edge cases - I'd love to hear about them.

GitHub (not fully operable, must be fine-tuned in some way)

This post is merely a cheatsheet focused on XM Cloud DevOps and deployment, which I left for myself to have all the important Sitecore CLI commands in one place.

SitecoreAI gives teams three paths for managing deployments: the DeployApp web UI in the Cloud Portal, the Deploy API REST endpoints, and the Sitecore CLI with the SitecoreAI plugin. This post focuses exclusively on the CLI path. Whether you are wiring up a GitHub Actions workflow, an Azure DevOps pipeline, or scripting a repeatable release process, the commands below are your complete reference.

Content

• Authentication
• Project and Environment Hierarchy
• Key Deployment Commands
• Decoupled Deployments Explained
• Serialization and Publishing Workflow
• Important Notes

Authentication

Before any CLI command can talk to Sitecore Cloud, you need an authenticated session. There are two modes.

Interactive login (developer workstations)

Opens a browser-based login flow, ideal for local development:

dotnet sitecore cloud login

Non-interactive login (CI/CD pipelines)

Pass client credentials directly with no browser prompt. This is the right option for automated pipeline steps:

dotnet sitecore cloud login   --client-credentials   --client-id <your-client-id>   --client-secret <your-client-secret>

Permission requirement: The authenticating identity must hold the Organization Admin or Organization Owner role in the Sitecore Cloud Portal. Without it, project and environment creation commands will be rejected.

Project and Environment Hierarchy

SitecoreAI organizes resources in a three-level hierarchy: Project, Environment, and Deployment. Each level must exist before you can create the next.

Create a project

dotnet sitecore cloud project create -n <projectname>

The command returns the project-id you will need for the next step.

Create an environment

# Non-production environment
dotnet sitecore cloud environment create   --name <environment-name>   --project-id <project-id>   --cm-only

# Production environment - add --prod for SLA coverage
dotnet sitecore cloud environment create   --name <environment-name>   --project-id <project-id>   --cm-only   --prod

Note on --cm-only: This flag signals a CM-only authoring environment topology. Deployment architecture options have evolved with the January 2026 decoupled model, so always verify the exact flag behaviour against the CLI plugin version in your project, as options may differ across releases.

Key Deployment Commands

Authoring environment (CM) deployment

This is the primary command to deploy your XM Cloud authoring environment. The --upload flag packages and uploads your repository directly from the CLI:

dotnet sitecore cloud deployment create   --environment-id <environment-id>   --upload

Editing host deployment

From January 2026 onward, the editing host is deployed as a separate unit. This command targets the editing host component independently:

dotnet sitecore cloud editinghost deploy   --environment-id <environment-id>   --upload

Repository size limit: The maximum repository size for --upload deployments is 500 MB. Plan your build pipeline to stay under this threshold, or use the Deploy API with a pre-built artifact URL for larger repositories.

Retrieving logs

There are two separate log surfaces worth knowing about: runtime environment logs and deployment-specific logs. Both are accessible via the CLI without touching the portal.

To list available log files for an environment:

Since the decoupled model produces independent logs per component, you will want to check environment logs for CM runtime issues and deployment logs for build or provisioning failures separately.list -id <environment-id> --latest

To print a runtime-specific log file directly to the console:

dotnet sitecore cloud environment log view -id <environment-id> --log <log-file-name>

You can also download a log file to a local path instead, which may be helpful for the cases oа implementing a "log drain" feature:

dotnet sitecore cloud environment log download -id <environment-id> --log <log-file-name> -o <output-path>

For deployment-specific logs (useful when diagnosing a failed or stuck deployment), use the deployment log command:

dotnet sitecore cloud deployment log -id <deployment-id> -o <output-path>

Note: Since the decoupled model produces independent logs per component, you will want to check environment logs for CM runtime issues and deployment logs for build or provisioning failures separately.

Decoupled Deployments Explained

The recommended deployment model since January 2026 separates the CM authoring environment from the Editing Host. Each component is deployed independently using its own CLI command:

• Authoring (CM): cloud deployment create --upload
• Editing Host (EH): cloud editinghost deploy --upload

The practical benefits of this approach:

• Faster release cycles - deploy the CM without rebuilding the EH, and vice versa
• Independent rollback - revert one layer without touching the other
• Granular observability - each component produces its own deployment logs, making root-cause analysis faster
• Pipeline flexibility - CI/CD stages can be parallelised or gated independently per component

Serialization and Publishing Workflow

Code deployment covers the application layer. Content serialization and Edge publishing are separate steps that run after the environment is live.

Step 1: Push serialized content to the CM

Sync your Sitecore Content Serialization items into the target environment:

dotnet sitecore serialization push -n <environmentName>

Step 2: Publish to Experience Edge

Once content is in the CM, publish it to Experience Edge so your head application can consume the updated data:

dotnet sitecore publish --pt Edge -n <environmentName>

Important Notes

• Repository size limit: 500 MB maximum for CLI uploads via --upload.
• Auto-deploy option: DeployApp offers a "Trigger deployment on commit to branch" setting. For pure CLI pipelines, replicate this by calling deployment create from a git webhook or pipeline trigger.
• Required role: Organization Admin or Organization Owner in the Sitecore Cloud Portal is required for creating projects and environments.
• Decoupled model: CM and EH deployed separately is the recommended approach since January 2026. Favour this for all new projects.
• Plugin version: Always run dotnet sitecore --version to confirm your XM Cloud plugin is current. Flag behaviour such as --cm-only may differ across plugin releases.

Are you using CLI or DeployApp for your CI/CD pipeline? Share your setup in the comments below!

When a GitHub Repository Stops You in Your Tracks

There are moments in a developer's life when you stumble across something on GitHub and your immediate, instinctive reaction is: "Wait - this should already exist everywhere." That was precisely my reaction when I landed on the official Sitecore Labs repository for the Layout Container component for XM Cloud.

If you work with Sitecore XM Cloud and Headless SXA, you will recognize the pain almost instantly. Your content authors want freedom, they want to build rich, multi-column, responsive page layouts without raising a development ticket. Your developers want to deliver clean, maintainable frontend code without copy-pasting bespoke wrapper <div> hierarchies all over the codebase. Your architects want a composable, reusable structural primitive that the entire team can rally around. And yet, out of the box, the XM Cloud Starter Kit leaves you to solve all of that yourself.

Enter the Layout Container - a deceptively simple name for a component that carries enormous potential. Built and published by the Sitecore Labs team (the same group that maintains the xmcloud-foundation-head starter kit and other first-party accelerators), this single component quietly addresses one of the most common friction points in any Headless SXA project: how do you give content authors meaningful layout control without handing them a blank canvas and a prayer?

What makes it truly exciting is what I'd call its universality. Unlike a "Hero" or a "Promo" component - which solves one specific presentational problem - the Layout Container is infrastructure. It is the scaffolding upon which every other component lives. Its scope is not a feature; it is a fundamental authoring primitive, and discovering it tucked away in a labs repository rather than shipped as a platform default is both a delight and, as we'll discuss, a genuine head-scratcher.

Let's dig into what this component actually does and why it matters so much.

Inside the Codebase - What Makes the Layout Container "Universal"

The repository is refreshingly lean. Its footprint consists of a LayoutContainer.tsx React/TypeScript component, a dedicated SCSS stylesheet folder, and a set of Sitecore-serialized content items that wire everything together on the Content Management side. That austerity is intentional - this is a utility component, and utility components should not carry unnecessary weight. But don't let the simplicity fool you: the architectural thinking behind it is substantial.

The Sitecore Item Architecture

The Sitecore side of the component is serialized using the Sitecore CLI (dotnet sitecore ser push) and lives under the familiar Headless Experience Accelerator rendering path: /sitecore/layout/Renderings/Feature/Headless Experience Accelerator/Layout Container.

This placement is deliberate and telling. By living under the Feature layer of the HEA namespace, right alongside the out-of-the-box Page Content components - the Layout Container is explicitly designed to behave as a peer to first-party SXA components, not a bolted-on afterthought. It is enabled through the site's Available Renderings configuration under the Page Structure group, which is exactly where structural components belong. This tells content authors unambiguously: "This component organizes other components. It is not content itself."

The module definition (layoutcontainer.module.json) follows the standard Sitecore CLI module pattern, meaning it integrates cleanly with existing serialization workflows. There is no custom build step, no exotic dependency, and no configuration magic required - just a clean dotnet sitecore ser push -i LayoutContainer and you are live.

The React Component: Flexibility Through Parameters

The heart of the component is LayoutContainer.tsx, a Next.js/React component following the canonical Headless SXA pattern that every XM Cloud developer will recognize:

type LayoutContainerProps = {
  params: { [key: string]: string };
  fields?: { [key: string]: Field };
};

This signature is significant. The heavy lifting in this component happens through params - the rendering parameters, rather than through datasource fields. This is the correct architectural choice for a structural component. Layout decisions (column count, spacing, background color, alignment) are rendering concerns, not content concerns. Using params instead of a datasource means the Layout Container does not pollute the content tree with structural data items, keeping the authoring experience clean and the content model honest.

The component dynamically assembles its CSS class list by composing values from its rendering parameters - including the built-in GridParameters that Headless SXA passes to every component. This means it inherits the full grid vocabulary of the SXA grid system right out of the box, without needing to reinvent it.

SCSS Architecture - Responsive by Design

The SCSS module (layout-container/) follows the same BEM-influenced, SCSS-variable-driven conventions used in the XM Cloud Starter Kit, making it trivially easy to integrate with an existing project's design token system. Rather than hardcoding breakpoint values or pixel measurements, the styles are structured to compose with the host project's existing _variables.scss and _mixins.scss infrastructure.

More importantly, the CSS is structured around CSS Grid and Flexbox semantics, giving it the full power of the modern layout cascade. This means:

• Column configurations (halves, thirds, quarters, asymmetric splits) are expressed as CSS Grid template columns, which adapt naturally to content reflow.
• Vertical stacking on mobile is handled via media query breakpoints that collapse multi-column grids to a single-column layout - no JavaScript required, no layout shift.
• Gap/spacing control maps to CSS gap properties, keeping spacing consistent with the browser's natural rendering model.

The upshot is a component whose visual output is responsive, accessible, and performant - not because of clever JavaScript, but because it leans on what CSS is already brilliant at.

Component Nesting: The Real Superpower

If you've been reading this and thinking "okay, it's a grid wrapper - so what?" - this is the part that should change your mind.

The Layout Container is designed to be infinitely nestable, both with itself and with any other Sitecore component. In XM Cloud Pages, because it appears in the Page Structure available renderings group, it can be dropped onto a page as a top-level structural element. But critically, it can also be placed inside another Layout Container, creating a recursive composition model that is genuinely rare in out-of-the-box Sitecore experiences.

Consider some concrete scenarios where this nesting capability becomes indispensable:

Scenario A: The Marketing Landing Page. A content author building a campaign page might want a full-width hero at the top, then a three-column content row (icons + text), then a two-column row (image left, rich text right), then a full-width CTA strip. Without the Layout Container, this requires a developer to hardcode multiple distinct page template zones or create bespoke wrapper components. With it, the author drops Layout Containers like building blocks - no development ticket required.

Scenario B: The Card Grid Within a Tab. A developer has built a Tabs component. Inside each tab, a content author wants to place a 2×3 grid of Card components. Without a nestable layout primitive, the developer either has to bake the grid logic into the Tabs component (coupling concerns that should be separate) or accept that the tab body is a single linear column. With the Layout Container nested inside the tab's placeholder, the author gets the grid; the developer keeps a clean separation of concerns.

Scenario C: Asymmetric Editorial Layouts. A content team building a magazine-style article page wants a wide left column for body text and a narrow right column for a related-links sidebar, with the sidebar itself containing a small two-column author bio grid. This is a nested grid - a layout inside a layout inside a layout. Without a universal container, you either write it in code (slow, inflexible) or you don't do it at all (bad for editors). With the Layout Container, the author assembles it themselves in Pages, live, without a deployment.

This nesting behavior is not merely a developer convenience - it is a fundamental empowerment of the content author role, and it is one of the clearest indicators that whoever designed this component understood the day-to-day reality of editorial workflows.

Configuration Options - What Authors Can Control

Based on the component's architecture and the Headless SXA rendering parameters pattern, the Layout Container exposes a meaningful set of authoring controls in XM Cloud Pages:

Grid Parameters inherit from the SXA grid system, allowing authors to choose how the container spans the page grid (full width, contained, offset columns). This is the same parameter available on every SXA component, so authors already know how to use it.

Custom CSS Classes / Styles can be passed as additional rendering parameters, enabling developers to pre-define named variants (e.g., "layout--highlight-band", "layout--dark-bg") that authors can select without touching code. This is the Headless SXA variant pattern applied at the structural level.

Column Count and Layout Mode parameters map to specific CSS Grid configurations in the SCSS module, letting authors switch between common layouts (equal columns, sidebar-left, sidebar-right, masonry-ready) through a simple dropdown in Pages - no CSS knowledge required.

Spacing Controls allow authors to add or remove padding between the container and its children, supporting the common design system requirement of consistent whitespace tokens (e.g., spacing-sm, spacing-md, spacing-lg).

The beauty of the params-based approach is that developers define the vocabulary (which class names and configurations are valid) while authors make the choices within that vocabulary. It strikes the precise balance between control and guardrails that every enterprise DXP project demands.

Reusability, Extensibility, and the Development Workflow

From a developer's perspective, the Layout Container represents a philosophy shift in how Headless SXA projects should be structured. Instead of building N bespoke two-column, three-column, or asymmetric-layout components - each with its own rendering definition, datasource template, and SCSS file - you build one structural primitive and compose everything else on top of it.

This has a profound effect on the development lifecycle:

• Onboarding time drops. New developers on the project only need to learn one layout abstraction, not a proliferating zoo of structural wrapper components.
• QA scope shrinks. One well-tested Layout Container component, rather than a dozen layout variants, means fewer regression paths when the design system updates.
• Extending it is trivial. Want to add a new layout variant (say, a five-column grid for a data dashboard)? Add a CSS class to the SCSS module, add the parameter value to the rendering parameters template in Sitecore, and the new layout is immediately available to content authors. The component code itself does not change.
• Designers and developers speak the same language. When the layout vocabulary is codified in a single component's parameter schema, design token changes and grid system updates have a single, clear, authoritative integration point.

Content authors, meanwhile, gain something that is often underestimated in its value: the confidence to experiment. When a layout is a drag-and-drop combination of Layout Containers and components rather than a hardcoded template, authors can try different page structures, get feedback from stakeholders, and iterate - all without waiting for a sprint cycle.

The Big Question - Why Isn't This Already in the Base Image?

Let's step back and state what should, by now, be obvious: the Layout Container component solves a universal problem. Not a vertical-specific problem. Not a "large enterprise only" problem. Not a "nice to have for power users" problem. Every single Headless SXA project built on XM Cloud needs a way for content authors to compose multi-column, responsive page layouts without developer intervention. Every. Single. One.

Which makes the central question of this post genuinely difficult to dismiss: Why is this component not shipped as a standard part of the XM Cloud Headless SXA base image?

The Starter Kit (xmcloud-foundation-head) ships with a solid collection of baseline components - Rich Text, Image, Promo, Navigation, Container, and others. These give teams a running start with content-level components. But the Layout Container - a structural primitive that sits one level of abstraction above all of those - is absent. Teams that don't discover this Labs repository must either build their own (reinventing the wheel, probably with less polish) or ship projects where content authors are constrained to the column structures that developers hardcoded during the initial build.

Consider the cumulative cost of that gap across the Sitecore partner and customer ecosystem. Every implementation team that has ever built a bespoke "TwoColumnLayout.tsx" or "SidebarWrapper.tsx" component - which is almost certainly every implementation team - has spent time solving a problem that this component already solves cleanly and correctly. That is not just redundant effort; it is inconsistent effort, producing different quality levels, different authoring experiences, and different maintenance burdens across the ecosystem.

There is also an onboarding and adoption story to consider. XM Cloud's pitch to new customers and partners includes the power of XM Cloud Pages and the visual, drag-and-drop composability of Headless SXA. But that pitch rings hollow if the first thing an author discovers is that they cannot create a two-column layout without filing a ticket. Including the Layout Container in the base image would make the out-of-the-box authoring experience substantially more compelling - not just for power users, but for day-one evaluators.

To be clear: the Sitecore Labs team deserves real credit for building this and publishing it openly. Making it available as a discoverable Labs component is genuinely better than not having it at all, and the quality of the implementation reflects careful thinking about how it should work within the Sitecore ecosystem. The installation guide is clear, the integration path is clean, and the component follows all the right conventions.

But "discoverable if you know to look for it" is a fundamentally different value proposition than "available by default." The former relies on developers reading the right blog posts (like this one, perhaps!), attending the right community sessions, or being lucky enough to have a colleague who found it first. The latter means every XM Cloud customer gets the benefit from day one - regardless of their implementation partner's GitHub browsing habits.

If the hesitation is about keeping the base image lean and avoiding "bloat," that concern is understandable but worth challenging. The Layout Container is not an opinionated business component - it carries no brand, no domain logic, and no content model assumptions. It is as unopinionated as a <div>. It is infrastructure. And infrastructure belongs in the foundation, not in a labs addendum.

If the hesitation is about support scope - that adding more components to the base increases the surface area Sitecore must maintain - then perhaps the answer is a tiered model: a curated "recommended additions" bundle that partners and customers can opt into during project setup, with the Layout Container as its flagship entry.

Whatever the path, the status quo is leaving value on the table. Every XM Cloud project that ships without this component, or ships with a lesser hand-rolled substitute, is a reminder of a gap that Sitecore Labs has already, quietly, filled. It's time to bring it in from the cold.

Have you considered integrating the Layout Container into your SitecoreAI project? Drop a comment below or reach out on the Sitecore Community Slack - I'd love to hear how your team has extended it, what rendering parameter configurations you've found most useful, and whether you've hit any edge cases with deep nesting in XM Cloud Pages. And if you haven't explored it yet, the GitHub repository is the place to start - your content authors will thank you for it.

Every year I create a special Christmas postcard to congratulate my readers on a new oncoming year, full of changes and opportunities. Wish you all the best in 2026!

The Sitecore MVP program recognizes individuals who have demonstrated advanced knowledge of the Sitecore platform and a commitment to sharing knowledge and technical expertise with community partners, customers, and prospects over the past year. The program is open to anyone passionate about Sitecore and eager to contribute to the community.

Over the past application year, starting from December 1st, 2024, I have been actively involved in the Sitecore community, contributing in a number of ways.

Sitecore Symposium 2025 Presentation

Together with Vasiliy Fomichev, we led a very insightful 50-minute workshop on building agentic copilots for Sitecore, during which Vasiliy provided the full theoretical foundation for the topic. I took it from there with a practical, hands-on demo of what it takes to make one from zero to the actual work, essentially giving the step-by-step instructions one could reproduce to get this done in under an hour. 

My demo showcased the effort and key decisions required to build a Microsoft Teams copilot, enabling marketers to perform specific operations (mass rebranding in our case, but could be anything) in the fastest, safest way. 

The whole chain looks as follows:

    Ms Teams ==> Teams Bot ==> LLM ==> Custom MCP Server ==> PowerShell ==> SPE (and the same reverse way back)

Recordings are available:

• My practical demo recording
• Full session recording (from my phone)

Agentic AI Challenge

Thrilled to be recognized as a Top 2nd Finalist in the Sitecore AI Challenge out of 150 submissions globally!

The AI Visibility app I've built will help SitecoreAI XM Cloud clients optimize their websites for AI within minutes. Like Michelle Boockoff-Bajdek mentioned, it's sometimes surprising to learn the fundamental questions people ask about your brand. Our app takes the guesswork out of AI optimization and helps Sitecore users gain a competitive advantage in digital. 

The app is now being reworked (implementing all the recent changes released after Sym) for review to join the public SitecoreAI Marketplace.

Awarding ceremony recording.

Sitecore Blogs 

This year, I have written 24 blog posts on various topics related to Sitecore, top-notch findings about XM Cloud and other composable products, best practices, tips and tricks, and case studies:

• Sitecore PowerShell working from a SitecoreAI Marketplace app
• Case Study: Search Solutions Comparison for Sitecore XM Cloud Migration
• The Game Has Changed: Sitecore AI and the Dawn of the Agentic Era
• Sitecore Content SDK 1.2 brings App Router into XM Cloud
• The new and shiny Sitecore Marketplace
• Auto-migrating any Sitecore XP website to XM Cloud is actually possible!
• Top 10 Mistakes Organizations Make on Sitecore XM Cloud Implementations
• Resolving broken images issue on XM Cloud starter kit running in local containers
• Changing item ID in XM Cloud from the item's context menu
• Dictionary in XM Cloud
• Using these XM Cloud hotkeys can significantly boost your productivity
• Using Sitecore Pipeline Profiler
• XM Cloud productivity tip: Use Cloud Portal Auto Login extension for Chrome
• SUGCON Europe 2025 Takeaways
• XM Cloud: Beyond the Serialization
• XM Cloud Headless Endpoints - Local vs Cloud vs Preview
• Sitecore XP vs XM Cloud full guide: which one to choose in 2025
• Compliance and Geographic Hosting Considerations for Sitecore XM/XP vs XM Cloud
• Redirects in Sitecore XM Cloud - know your options!
• SQL-level access to the database in XM Cloud
• All you need to know about transforming Web.config on Sitecore XM Cloud
• Rendering Parameters vs. Rendering Variants - when should we use one or another
• Experience Edge: Know Your Limitations
• Sitemaps in Sitecore XM Cloud: Automation, Customization, and SEO Best Practices

YouTube Videos

I have reverse-engineered the Sitecore PowerShell Extension and reassembled it into a SitecoreAI Marketplace app!

This PoC is essentially a blueprint app. On its own, it is a universally working example. Still, its real benefit comes from this app providing a ready-to-use boilerplate that can be reused to build a variety of specialized SitecoreAI Marketplace apps on top of the SPE approach.

The most awesome feature is that all of your Marketplace context values could be easily passed into a remotely executed PowerShell script as a script parameter: there is a convenient Script Parameters mapping with maramater token preview (so that you never miss the right value!)

Here's what it looks like:

To enable SPE with Remoting:

1. From SitecoreAI Deploy, add SPE_REMOTING_SECRET environmental CM secret, then re-deploy.
2. Install a package, which will enable SPE with Remoting: SPE_with_Remoting.zip (3.93 kb)
3. This package also adds a disabled sitecore\speremoting user with admin rights, which you must enable manually from User Manager

Once this setup is complete, the environment is fully prepared to use the app. The Marketplace app supports multitenancy; however, SPE Remoting must be enabled individually for every environment you intend to work with.

1. Introduction

This case study presents a high-level comparison of four leading search solutions - Coveo, Sitecore Search, Algolia, and SearchStax - for a Benelux-based financial organization considering a migration to Sitecore AI. The analysis focuses on licensing costs, implementation effort, potential hidden fees, technical limitations, and the availability of React-based frontend SDKs for each platform. The goal is to provide the necessary information to enable an informed decision on whether to migrate from Sitecore XP and to determine which solution best suits the organization's needs and budget.

The website has the following traffic characteristics, taken into consideration:

• Annual Traffic: ~700K sessions in 2024 and ~850K sessions in 2023.
• Components: ~160 unique components.
• Budget Expectations: under to €10K for a “composable” (external) search provider

Section 4 of this document contains the conclusion and the considered recommendation based on the balance of individual organizations’ parameters.

2. Executive Summary

The following table provides a high-level comparison of the four search solutions:

3. Detailed Analysis

3.1. Coveo

Coveo is a powerful, AI-driven enterprise search platform that offers advanced personalization and relevance tuning capabilities. It is a mature product with a strong presence in the Sitecore ecosystem, well-suited for large organizations with complex search requirements.

Licensing and Cost

Coveo's pricing is geared towards enterprise clients and is generally the highest of the four options. The pricing model is based on a combination of query volume and the number of indexed items, with subscriptions typically sold on an annual or multi-year basis.

• Coveo for Sitecore Plans: The Pro+ plan starts at 200,000 queries per month, while the Enterprise+ plan starts at 300,000 queries per month and offers volume-based pricing. Given the client's traffic, they would likely fall into the lower tiers of these plans.
• Implementation Cost: A typical enterprise-level deployment, including licensing and professional services, can range from $50,000 to over $100,000 USD. This does not include ongoing maintenance or support costs.
• Hidden Fees: Additional costs can arise from add-on features such as Generative AI, advanced security, and dedicated technical support. Overages on query limits are handled through a discussion with a customer manager rather than automatic charges, providing some flexibility but also potential for unexpected cost increases.

Implementation Effort

Coveo's integration with Sitecore is well-documented and mature, but it is not a simple plug-and-play solution. The platform's power and flexibility come at the cost of increased complexity.

• Complexity: Coveo has a steep learning curve and often requires dedicated developer time to configure even moderately complex use cases.
• Expertise: Successful implementation typically requires specialized knowledge of the Coveo platform, and many organizations opt for professional services from Coveo or a certified partner.
• Time to Value: The complexity of configuration and optimization can lead to a longer implementation timeline compared to other solutions.

React SDK and Frontend Components

Coveo provides a comprehensive set of tools for building modern search UIs with React.

• Coveo Atomic React (@coveo/atomic-react): A React wrapper around the core atomic web component library, providing a rich set of components for building search interfaces.
• Plasma Design System: A React-based design system used in the Coveo Cloud Administration Console, which can be leveraged for a consistent look and feel.

Technical Limitations

While powerful, Coveo does have its limitations.

• File Size: The maximum size for a single indexed item is approximately 256 MB, which includes metadata and permissions.
• Configuration Complexity: The platform's extensive features can be difficult to manage, and the documentation is sometimes considered vague or incomplete.
• Cost at Scale: Although the client's current traffic is low, a significant increase in search queries or indexed content could result in substantial cost increases.

3.2. Sitecore Search

Sitecore Search is the native search solution for the Sitecore ecosystem, designed to provide a seamless and integrated experience. It is an AI-powered, headless platform that focuses on delivering personalized and predictive search results.

Licensing and Cost

Detailed pricing for Sitecore Search is not publicly available and requires a direct quote from Sitecore. However, it is often bundled as part of the unified SitecoreAI (ex. XM Cloud) offering, which can make it a cost-effective option for organizations already invested in the Sitecore ecosystem.

• Pricing Model: The cost is likely tied to the overall Sitecore contract and may not be broken down as a separate line item. This can simplify budgeting, but also makes it difficult to compare directly with other solutions.
• Implementation Cost: As a native solution, the initial setup is generally more straightforward than third-party integrations. However, customization and optimization will still require development effort.
• Hidden Fees: Potential hidden costs could arise if the bundled search capacity is exceeded.

Implementation Effort

Sitecore Search is designed for seamless integration with XM Cloud, which should reduce the initial implementation effort compared to third-party solutions.

• Native Integration: The platform is designed to seamlessly integrate with Sitecore's content models and personalization features, streamlining the integration process.
• Developer Expertise: Implementation can typically be handled by developers with standard Sitecore expertise, without requiring specialized third-party knowledge.
• Time to Value: Native integration and a familiar development environment can lead to a faster time to value for most projects.

React SDK and Frontend Components

Sitecore provides a native and well-supported React SDK for building search experiences.

• Sitecore Search JS SDK for React: A dedicated SDK that allows developers to quickly integrate search experiences into React applications. It includes a full set of UI components and a starter kit to accelerate development.

Technical Limitations

As a relatively new product, Sitecore Search has some limitations and operational challenges that need to be considered.

• Indexing Delays: Crawling content from multiple sites with a single source can lead to prolonged indexing times, sometimes exceeding an hour. This can be a significant issue for time-sensitive content.
• Scalability: For large, multi-site implementations, it is recommended to create separate sources for each site to improve indexing efficiency. This adds a layer of management complexity.
• Real-Time Updates: The platform currently relies on full crawls for index updates, and there is a lack of a "Push API" for immediate, incremental updates. This can result in a delay of several minutes for new content to appear in search results.

3.3. Algolia

Algolia is a developer-focused search-as-a-service platform known for its speed and real-time capabilities. It provides a flexible and powerful set of APIs that enable the creation of fast and responsive search experiences.

Licensing and Cost

Algolia's pricing is transparent and based on a pay-as-you-go model, making it very cost-effective for organizations with low to moderate search traffic. For the client's current traffic levels, the costs would be minimal.

• Pricing Model: The Grow and Grow Plus plans offer a free tier of 10,000 search requests per month, with additional requests billed at a low rate of $1,000 per 1,000 requests. The number of records (~350 pages) is well within the free tier of 100,000 records.
• Cost Estimate: Based on the client's average annual traffic of ~775,000 sessions, the estimated annual licensing cost for Algolia would be between $17 and $197 USD, depending on the plan and the actual search rate.
• Hidden Fees: The primary "hidden" cost with Algolia is the implementation effort, as there is no native Sitecore connector. While the licensing is inexpensive at this scale, a significant increase in traffic or a move to the enterprise Elevate plan could result in substantial cost increases, with average enterprise plans costing around $350,000 annually.

Implementation Effort

While Algolia is known for its developer-friendly APIs, the lack of a native Sitecore connector means that integration requires custom development.

• Custom Integration: Implementing Algolia with Sitecore requires building a custom integration to index content and create the search interface. This can be a time-consuming and expensive process.
• Third-Party Connectors: Third-party connectors are available, such as the "Algolia Index Builder for Sitecore" by Brimit, which can simplify the integration process. However, these connectors may come with their own licensing costs and support limitations.
• Developer Expertise: The implementation requires developers with experience in both Sitecore and API-based integrations.

React SDK and Frontend Components

Algolia offers an actively maintained open-source React library.

• React InstantSearch (react-instantsearch): A comprehensive library that lets developers create an instant search result experience with a rich set of pre-built widgets. It is highly performant and customizable.

Technical Limitations

Algolia's focus on speed and simplicity comes with some trade-offs.

• Manual Tuning: Achieving high search relevance often requires manual tuning and configuration of the search algorithm.
• eCommerce Features: While it can be used for e-commerce, it has limited specialized features compared to platforms like Coveo.
• Indexation Time: Some users have reported that indexation time can be a factor that impacts user experience, particularly for large and complex datasets.

3.4. SearchStax

SearchStax offers both a fully managed site search solution (Site Search) and a managed Apache Solr hosting service (Managed Search). For a Sitecore XM Cloud implementation, the Site Search product is the most relevant, as it is designed to integrate directly with modern, headless architectures.

Licensing and Cost

SearchStax Site Search pricing is based on a tiered subscription model, with the entry-level Essential plan starting at $799 per month (billed annually).

• Pricing Model: The plans scale based on the number of indexed items, monthly searches, and advanced features. The Advanced and Premium plans require a custom quote.
• Implementation Cost: The cost of implementation is moderate, as SearchStax provides a dedicated Sitecore module and UI kits to accelerate development.
• Hidden Fees: Additional costs could arise from overages on search requests or indexed items, or from the need for advanced security and support add-ons available with the Managed Search product.

Implementation Effort

SearchStax has invested in creating a smooth integration experience for Sitecore users, including those on XM Cloud.

• Sitecore Integration: SearchStax offers a dedicated module for Sitecore, which connects directly to the Site Search solution, as well as connectors for their Managed Search product.
• Developer Expertise: The availability of UI kits and pre-built components reduces the required level of specialized expertise, allowing developers with standard React and Sitecore knowledge to implement the solution effectively.
• Time to Value: The combination of a dedicated Sitecore module and React UI kits can significantly accelerate the development process and reduce the time to value.

React SDK and Frontend Components

SearchStax provides a comprehensive set of tools for building search interfaces with React.

• Search UI Kits: SearchStax offers UI kits for JavaScript, Vue, Angular, and React/Next.js, which include pre-built components to streamline the development of the search UI.

Technical Limitations

SearchStax has some service limits in place to ensure stability and performance.

• API and Document Limits: There are limits on API requests per second (20+), document size (100KB), and payload size (10MB).
• Feature Limits: There are also limits on the number of facet values (50), promoted items (10), and other features.
• User-Reported Issues: Some users have reported that the platform can be expensive and that there are limitations on the number of search results that can be displayed per category.

4. Conclusion and Recommendations

Each of the four search solutions offers a viable path for a Sitecore XM Cloud migration, but they cater to different priorities and budgets. The availability of React-based SDKs and component libraries from all four vendors is a significant advantage, as it simplifies the development of the front-end search experience.

1. Coveo remains the top-tier enterprise solution, offering the most advanced AI and personalization features. Its high cost is justified by its power and its proven track record in the financial services industry.
2. Sitecore Search provides the tightest integration with the SitecoreAI ecosystem, which can lead to a more streamlined implementation and a unified user experience.
3. Algolia is the most budget-friendly option for the client's current traffic, but the lack of a native Sitecore connector and some basic features introduces significant implementation risk and long-term maintenance overhead.
4. SearchStax presents a compelling middle ground. It offers a robust, AI-powered search solution with a clear integration path for Sitecore XM Cloud and a more accessible price point than Coveo. Its managed Solr foundation provides a high degree of security and reliability.

Recommendations

1. Primary Recommendation: Sitecore Search.It should be considered a seamless, all-in-one solution from a single vendor, thus natively fits in the product space. A thorough proof of concept is essential to validate that its performance and scalability meet the client's needs. Native integration and the presence of the best-breed front-end components make this choice the best balance among these platforms. It totally fits the aligned budget. Additionally, it features AI personalization capabilities and operates within the newly created Unified Data, alongside XM Cloud (for tracking, analytics, personalization, and more).
2. For a financial institution that prioritizes a premium, secure, and highly personalized user experience, Coveo could be a recommended solution. Its enterprise-grade features and strong compliance posture are well-suited to the needs of the financial services industry. However, due to budget concerns, Coveo is not a suitable option. Coveo's minimal tier times exceed the organization’s desired budget range.
3. Strong Alternative: SearchStax.If the cost of Coveo is a significant barrier, SearchStax is a strong alternative. It provides a powerful, AI-driven search experience with a supported integration path for Sitecore XM Cloud. Its balance of features, cost, and ease of implementation makes it a very attractive option. However, despite being a budget option, the total cost of ownership can often be higher compared with Sitecore Search and Algolia.
4. Budget-Constrained Option: Algolia.Algolia should only be considered if the budget is the primary driver, and the organization has a strong in-house development team to manage custom integration. The long-term total cost of ownership may be higher than the initial licensing fees suggest.

The choice between Sitecore Search and SearchStax will likely come down to a trade-off between the advanced, integrated features of the native Sitecore product and yet still powerful solution offered by SearchStax.

5. References

• Coveo Pricing
• Coveo for Sitecore Pricing
• Why Use Coveo Enterprise Search Software
• Coveo Platform Limits
• Coveo File Size Limit
• Sitecore Search Pricing on TrustRadius
• Sitecore Search Accelerate Cookbook
• Addressing Operational Challenges in Sitecore Search
• Algolia Pricing
• Algolia Pricing: Is it Worth The Money?
• Comparing All The Options For Website Search in Sitecore
• Algolia Index Builder for Sitecore by Brimit
• Algolia Alternatives
• Why we churned from Algolia
• Coveo Atomic React Wrapper
• Coveo Plasma Components
• Sitecore Search JS SDK for React
• Sitecore Search JS SDK Starter Kit
• Algolia React InstantSearch
• SearchStax Site Search Pricing
• SearchStax Managed Search Pricing
• SearchStax Sitecore Module
• Building Sitecore Search with SearchStax Search UI Components
• SearchStax Site Search Service Limits
• SearchStax Reviews on G2

Why the Marketplace Matters: The Strategic Context

Currently, you can build Custom Apps, which are available to your organization and any other organizations you explicitly authorize. Public Apps, which will be available to all Sitecore customers through the Marketplace, are coming in a later release. Public apps will undergo a quality review process, which is a good thing for the ecosystem.

Architecture: Making the Right Choice

The architecture you choose for your Marketplace app has significant implications for what you can build and how complex your development will be. There are two main patterns:

1. Client-Side Architecture

In a client-side architecture, your app runs entirely in the user's browser. All API requests to Sitecore APIs are proxied through the browser using the SDK. This is the simplest option and is ideal for:

• UI extensions and custom fields
• Dashboard widgets
• Simple data visualization
• Apps that don't require server-side processing

The key advantage is simplicity. You can build a client-side app with just React or Vue, deploy it as a static site, and you're done. The SDK handles all the authentication and communication with Sitecore automatically.

2. Full-Stack Architecture

A full-stack architecture includes both client-side and server-side components. This is necessary when you need to:

• Make direct server-to-server API calls to Sitecore
• Integrate with AI services (like OpenAI, Anthropic, etc.)
• Perform heavy processing or data transformations
• Implement agentic workflows
• Store and manage your own data

For full-stack apps, you'll need to use custom authorization with Auth0. This is more complex to set up, but it gives you the flexibility to build sophisticated applications. My AI Challenge submission is a full-stack app because it integrates with multiple AI services and requires server-side orchestration.

3. Authorization: Built-in vs. Custom

The Marketplace SDK supports two authorization patterns:

• Built-in Authorization: The SDK automatically manages authentication. This is the default and recommended option for client-side apps.
• Custom Authorization (Auth0): Required for server-side API calls. You'll need to configure Auth0 credentials in the Developer Studio and handle session invalidation when your app is available in multiple organizations.

For your first app, I strongly recommend starting with client-side architecture and built-in authorization. Get something working, understand the SDK, and then move to full-stack if you need to.

Extension Points: Where Your App Lives

Extension points are the designated areas in the Sitecore UI where your app can be displayed. Understanding them is crucial to designing a great user experience.

1. Standalone (Cloud Portal)

Your app appears on the Cloud Portal home page in the "Marketplace apps" section. It opens in a new tab under the navigation header. This is ideal for apps that are used independently of XM Cloud, like reporting dashboards or administrative tools.

Image source: cloud portal app configuration screen

2. XM Cloud Full Screen

Your app is listed in the "Apps" dropdown in the XM Cloud navigation header and appears full screen. This is perfect for apps that need a lot of screen real estate, like content migration tools or complex configuration interfaces.

Image source: cloud portal app configuration screen

3. XM Cloud Page Builder Context Panel

This is one of my favorite extension points. Your app appears in the context panel to the left of the Page Builder canvas. This is ideal for page-level extensions, like:

• Real-time analytics insights
• SEO analysis tools
• Content quality checkers
• HTML validators

The context panel is always visible while editing a page, so your app is right there when users need it.

4. XM Cloud Page Builder Custom Field

Your app appears in a modal when a user clicks "Open app" on a custom field. This is perfect for:

• Icon pickers
• Color pickers
• External data selectors
• Media libraries

I've seen some brilliant implementations of this extension point, including a Material UI icon picker with over 10,000 icons.

Image source: cloud portal app configuration screen

5. XM Cloud Dashboard Widget

Your app can be added as a draggable widget to the XM Cloud site dashboard. This is ideal for displaying site-wide metrics, like bounce rates, popular pages, or performance data from third-party analytics tools.

The Marketplace SDK: A Deep Dive

The Sitecore Marketplace SDK is the foundation of all Marketplace development. It's open-source, well-documented, and a pleasure to work with. Let's dive into the details.

1. Package Structure

The SDK is divided into distinct packages:

• @sitecore-marketplace-sdk/client: Required for all apps. Handles secure communication between your app and Sitecore.
• @sitecore-marketplace-sdk/xmc: Optional. Provides type-safe interfaces for XM Cloud APIs, including queries, mutations, and subscriptions.

2. Getting Started: The 5-Minute Quickstart

Here's how you can get a basic Marketplace app running in about 5 minutes:

1. Create a new Next.js or Vite app:

npx create-next-app@latest my-marketplace-app
cd my-marketplace-app

2. Install the SDK packages:

npm install @sitecore-marketplace-sdk/client @sitecore-marketplace-sdk/xmc

3. Create a custom hook for the Marketplace client:

// hooks/useMarketplaceClient.ts
import { useEffect, useState } from 'react';
import { ClientSDK } from '@sitecore-marketplace-sdk/client';

export const useMarketplaceClient = () => {
    const [client, setClient] = useState<ClientSDK | null>(null);
    const [isInitialized, setIsInitialized] = useState(false);
    const [error, setError] = useState<Error | null>(null);

    useEffect(() => {
        const initClient = async () => {
            try {
                const sdkClient = new ClientSDK({
                    onError: (err) => {
                        console.error('SDK Error:', err);
                        setError(err);
                    }
                });

                await sdkClient.initialize();
                setClient(sdkClient);
                setIsInitialized(true);
            } catch (err) {
                setError(err as Error);
            }
        };

        initClient();
    }, []);

    return { client, isInitialized, error };
};

4. Use the client in your component:

// app/page.tsx
"use client"
import { useMarketplaceClient } from '@/hooks/useMarketplaceClient';
import { ApplicationContext } from '@sitecore-marketplace-sdk/client';
import { useState, useEffect } from 'react';

export default function Home() {
    const { client, error, isInitialized } = useMarketplaceClient();
    const [appContext, setAppContext] = useState<ApplicationContext | null>(null);

    useEffect(() => {
        if (isInitialized && client) {
            client.query('application.context')
                .then((res) => {
                    if (res.data) {
                        console.log('Application context:', res.data);
                        setAppContext(res.data);
                    }
                })
                .catch((err) => console.error('Query failed:', err));
        }
    }, [isInitialized, client]);

    if (error) {
        return <div>Error initializing SDK: {error.message}</div>;
    }

    if (!isInitialized) {
        return <div>Initializing Marketplace SDK...</div>;
    }

    return (
        <div>
            <h1>My Marketplace App</h1>
            {appContext && (
                <div>
                    <p>Organization: {appContext.organization.name}</p>
                    <p>User: {appContext.user.email}</p>
                </div>
            )}
        </div>
    );
}

That's it. You now have a working Marketplace app that can communicate with Sitecore.

3. Queries, Mutations, and Subscriptions

The SDK provides three main ways to interact with Sitecore APIs

 

1. Queries: Reading Data

Queries are used to retrieve data from Sitecore. Here are some common examples:

// Get application context
const contextResult = await client.query('application.context');

// Get list of sites
const sitesResult = await client.query('sites.list', {
    contextId: appContext.tenant.id
});

// Get a specific page
const pageResult = await client.query('pages.get', {
    contextId: appContext.tenant.id,
    pageId: 'your-page-id'
});

2. Mutations: Writing Data

Mutations are used to create, update, or delete data in Sitecore:

// Create a new template
const templateResult = await client.mutate('templates.create', {
    contextId: appContext.tenant.id,
    name: 'My Custom Template',
    baseTemplates: ['{1930BBEB-7805-471A-A3BE-4858AC7CF696}']
});

// Create a new item
const itemResult = await client.mutate('items.create', {
    contextId: appContext.tenant.id,
    parentId: 'parent-item-id',
    templateId: 'template-id',
    name: 'My New Item',
    fields: {
        Title: 'My Item Title',
        Text: 'My item content'
    }
});

// Delete an item
await client.mutate('items.delete', {
    contextId: appContext.tenant.id,
    itemId: 'item-to-delete'
});

3. Subscriptions: Real-Time Updates

Subscriptions allow your app to receive real-time updates when data changes in Sitecore. This is particularly useful for Page Builder extensions:

// Subscribe to page changes
const unsubscribe = client.subscribe('pages.changed', (data) => {
    console.log('Page changed:', data);
    // Update your UI accordingly
});

// Don't forget to unsubscribe when your component unmounts
useEffect(() => {
    return () => {
        if (unsubscribe) {
            unsubscribe();
        }
    };
}, []);

4. Context Management: Application vs. Pages

The SDK provides two types of context:

Application Context is available in all extension points and includes:

• Tenant and resource IDs
• Environment details
• User information and permissions
• Organization data

Pages Context is only available in Page Builder extension points and includes:

• Current page information
• Site details and configuration
• Real-time updates via subscriptions

Understanding which context is available in your extension point is crucial for building the right user experience.

Example of both contexts as they feed the Page Content Panel Extension point

Server-Side Logic with Next.js

For full-stack apps, you'll need to make server-side API calls to Sitecore. The SDK provides an experimental server-side client for this purpose:

// app/api/items/route.ts
import { experimental_createXMCClient } from '@sitecore-marketplace-sdk/xmc';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
    try {
        // Get the access token from the Authorization header
        const authHeader = request.headers.get('Authorization');
        if (!authHeader) {
            return NextResponse.json(
                { error: 'Missing authorization' },
                { status: 401 }
            );
        }

        const accessToken = authHeader.replace('Bearer ', '');

        // Get the context ID from the request body
        const { contextId, itemData } = await request.json();

        // Create the XMC client
        const xmcClient = experimental_createXMCClient({
            accessToken,
            contextId
        });

        // Make the API call
        const result = await xmcClient.items.create({
            parentId: itemData.parentId,
            templateId: itemData.templateId,
            name: itemData.name,
            fields: itemData.fields
        });

        return NextResponse.json(result);
    } catch (error) {
        console.error('Server-side API call failed:', error);
        return NextResponse.json(
            { error: 'Failed to create item' },
            { status: 500 }
        );
    }
}

The key pattern here is:

1. Get the access token from the Authorization header
2. Get the context ID from the request
3. Create the XMC client with both
4. Make your API calls
5. Handle errors appropriately

Styling: Blok vs. shadcn/ui

Sitecore recommends using Blok, their official design system, for Marketplace apps. Blok ensures your app looks and feels like a native part of Sitecore, and it includes built-in accessibility compliance.

However, many developers (myself included) prefer shadcn/ui for its flexibility and modern design. There's even a project called blok-shadcn that combines the best of both worlds, providing shadcn/ui components styled to match Sitecore's design language.

For my AI Challenge app, I used shadcn/ui with custom Sitecore-inspired theming, and the results have been excellent.

Development Best Practices

After building several Marketplace apps, here are some best practices I've learned:

1. Local Development with Hot Reload

During development, set your deployment URL to https://localhost:3000 (or whatever port you're using). This allows you to test your app in the actual Sitecore UI while developing locally. You'll need to use HTTPS, even locally. For Vite apps, use vite-plugin-mkcert. For Next.js, use mkcert to generate self-signed certificates.

2. Start Simple, Add Complexity Gradually

Don't try to build a full-stack app with AI integration on your first attempt. Start with a simple client-side app that displays some data. Get comfortable with the SDK, understand the extension points, and then add complexity.

3. Leverage TypeScript

The SDK is built with TypeScript, and the type definitions are excellent. Use them. They'll save you hours of debugging and make your code more maintainable.

4. Handle Errors Gracefully

The Marketplace SDK can throw errors for various reasons: network issues, authentication problems, invalid queries, etc. Always handle errors gracefully and provide meaningful feedback to users.

5. Test in Multiple Environments

Make sure your app works in all the environments where it will be used: local, dev, staging, and production. Pay special attention to CORS issues and authentication edge cases.

Hosting and Deployment

Since you host your own apps, you have complete control over your deployment strategy. Here are some popular options:

• Vercel: Excellent for Next.js apps. Automatic deployments from Git, great performance, generous free tier.
• Netlify: Great for static sites and Vite apps. Easy to set up, good CI/CD integration.
• Azure Static Web Apps: Good choice if you're already in the Azure ecosystem.
• AWS Amplify: Another solid option with good integration with other AWS services.

For my AI Challenge app, I'm using Vercel, and the deployment workflow is seamless: push to Git, and Vercel automatically builds and deploys.

Learning Resources: A New Developer Course

To further support the community, the Sitecore Learning team is releasing a new developer course for the Marketplace. While the course isn't available yet, you can see the announcement from Learning Team on LinkedIn. This is a fantastic initiative that will help onboard even more developers to the Marketplace ecosystem.

My AI Challenge Experience: Lessons Learned

Participating in the AI Challenge has been an incredible learning experience. Our proposal made us to the finals, and today I'm completing the final submission. 

Here are some key lessons I've learned:

• The Marketplace enables rapid innovation. I was able to go from idea to working prototype in a matter of days, not weeks or months.
• The SDK is that good.
• Full-stack architecture is essential for AI apps. If you're building anything that involves AI services, you'll need server-side logic.
• The experimental XMC client makes this straightforward.

My team and I ended up creting an AI marketplace extension that optimizes any of your page-under-edit for the agentic engines, by creating brand-aware content that will be consumed by agents parsing the site and therefore - affecting its LLM's output. IT also suggests how this page could get optimized according to schema.org markup for the better LLM parsers consumption:

Throughout the challenge, I've been in contact with other developers, sharing ideas and solving problems together. This is what makes Sitecore and its community very special.

What's Next?

The Sitecore Marketplace is more than just a new feature; it's a fundamental shift in how Sitecore approaches product development. By empowering the community to build and share apps, Sitecore is effectively multiplying their own development capacity. This is brilliant strategy.

The community has always been Sitecore's greatest strength. We've built modules, shared knowledge, and pushed the platform forward for years. The Marketplace is Sitecore's way of saying: 

"We trust you. We value you. Let's build the future together."

If you're a Sitecore developer or architect, I encourage you to start exploring the Marketplace today. Build something small, get comfortable with the SDK, and then tackle something more ambitious. The barrier to entry is low, and the potential is enormous.

What will you build? A custom field? A dashboard widget? An AI-powered content assistant? 

The possibilities are endless. I'd love to hear your thoughts.

References:

1. Official Sitecore Marketplace Documentation
2. Marketplace SDK on GitHub
3. Sitecore Learning Course Announcement