Getting Started with Building Custom Apps for Sitecore XM Cloud Marketplace

 


The Sitecore App Marketplace for XM Cloud Has Officially Launched

The Sitecore App Marketplace for XM Cloud is now live, opening up extensive possibilities for customizing and extending the platform. This blog consolidates the key development and configuration steps to help you build your first custom app.

I began by setting up a basic standalone application in XM Cloud to understand how the process works. With this capability, you can now create custom tools for your organization—or even apps for the broader Sitecore community. In this blog, we’ll walk through the essential steps to build an app in your development environment and then register and install it in XM Cloud.


What is the Sitecore Marketplace?

The Sitecore Marketplace enables customers, partners, and developers to build and use applications that extend Sitecore’s functionality. This means you can integrate your custom modules into Sitecore XM Cloud through various extension points.

These apps can be:

  • Private (available only to your organization), or

  • Public (shared with anyone using XM Cloud, though the public marketplace is not available yet).

Prerequisites

Before you start, ensure you have the following:

  • Access to Sitecore Cloud Portal – Marketplace apps are currently available only to Organization Owners and Admin users.

  • Development Environment – Node.js 16+ and npm 10+.

  • Basic Web Development Skills – TypeScript and React.

Extension Points: Where Your App Will Appear

When configuring your app, you can choose where in the Sitecore UI it should be visible. Available extension points include:

  • Standalone applications in the Portal

  • Full-screen experiences in XM Cloud

  • XM Cloud site dashboard widgets

  • Page Builder panel applications

  • Page Builder custom fields

For more detail- visit Overview of extension points

Step 1: Create Your App in Cloud Portal

  1. Log in to the Cloud Portal using an Admin or Owner account.

  2. Navigate to Developer Studio > Create App.


  3. Enter the details:

    • Descriptive name (max 50 characters).

    • Select Custom as the app type.



       4. Click Create – your app is now registered and ready for configuration.

Step 2: Configure Your App

  • Extension Points: Choose where your app should appear. You can select multiple points and customize the Route URL or Display Name.

  • API Access: Select the APIs your app will use. For XM Cloud integration, enable XM Cloud APIs.


  • Development URL:

    • React apps → http://localhost:5173

    • Next.js apps → http://localhost:3000

  • App Logo: Add a public logo URL (or use a temporary one: https://cdn-1.webcatalog.io/catalog/sitecore/sitecore-icon.png?v=1731337318728).

  • Activate App: Click Activate > Activate.



Step 3: Set Up Your Development Project

Create a Next.js or React app:

Next.js

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

React

npm create vite@latest my-test-app
cd my-test-app

Install required SDK packages:

npm install @sitecore-marketplace-sdk/client 
npm install @sitecore-marketplace-sdk/xmc # if your app uses XM Cloud APIs




Step 4: Create the useMarketplaceClient Hook
Create a custom hook to manage the SDK initialization. In your src folder, 
create /utils/hooks/useMarketplaceClient.ts, and paste the below code:

// utils/hooks/useMarketplaceClient.ts
import { ClientSDK } from "@sitecore-marketplace-sdk/client";
import { useEffect, useState, useCallback, useMemo, useRef } from "react";
export interface MarketplaceClientState {
client: ClientSDK | null;
error: Error | null;
isLoading: boolean;
isInitialized: boolean;
}

export interface UseMarketplaceClientOptions {
retryAttempts?: number; // Default: 3
retryDelay?: number; // Default: 1000ms
autoInit?: boolean; // Default: true
}

const DEFAULT_OPTIONS: Required<UseMarketplaceClientOptions> = {
retryAttempts: 3,
retryDelay: 1000,
autoInit: true,
};

let client: ClientSDK | undefined = undefined;

async function getMarketplaceClient() {
if (client) {
return client;
}
const config = {
target: window.parent,
};
client = await ClientSDK.init(config);
return client;
}

export function useMarketplaceClient(options: UseMarketplaceClientOptions = {}) {
const opts = useMemo(() => ({ ...DEFAULT_OPTIONS, ...options }), [options]);

const [state, setState] = useState<MarketplaceClientState>({
client: null,
error: null,
isLoading: false,
isInitialized: false,
});

const isInitializingRef = useRef(false);

const initializeClient = useCallback(async (attempt = 1): Promise<void> => {
let shouldProceed = false;
setState(prev => {
if (prev.isLoading || prev.isInitialized || isInitializingRef.current) {
return prev;
}
shouldProceed = true;
isInitializingRef.current = true;
return { ...prev, isLoading: true, error: null };
});

if (!shouldProceed) return;

try {
const client = await getMarketplaceClient();
setState({
client,
error: null,
isLoading: false,
isInitialized: true,
});
} catch (error) {
if (attempt < opts.retryAttempts) {
await new Promise(resolve => setTimeout(resolve, opts.retryDelay));
return initializeClient(attempt + 1);
}
setState({
client: null,
error: error instanceof Error ? error : new Error('Failed to initialize MarketplaceClient'),
isLoading: false,
isInitialized: false,
});
} finally {
isInitializingRef.current = false;
}
}, [opts.retryAttempts, opts.retryDelay]);

useEffect(() => {
if (opts.autoInit) {
initializeClient();
}
return () => {
isInitializingRef.current = false;
setState({
client: null,
error: null,
isLoading: false,
isInitialized: false,
});
};
}, [opts.autoInit, initializeClient]);

return useMemo(() => ({
...state,
initialize: initializeClient,
}), [state, initializeClient]);

}


This hook handles:
  • SDK initialization
  • Error handling and retry logic
  • Preventing race conditions
Step 5: Use the Hook in Your App
In your main app component (e.g., App.tsx or pages/index.tsx), import and use the hook.
For Next.js (pages/index.tsx):

import { useState, useEffect } from "react";
import type { ApplicationContext } from "@sitecore-marketplace-sdk/client";
import { useMarketplaceClient } from "../utils/hooks/useMarketplaceClient";
 
export default function Home() {
  const { client, error, isInitialized, isLoading } = useMarketplaceClient();
  const [appContext, setAppContext] = useState<ApplicationContext>();
 
  useEffect(() => {
    if (!error && isInitialized && client) {
      client.query("application.context")
        .then((res) => {
          setAppContext(res.data);
        })
        .catch((error) => {
          console.error("Error retrieving application.context:", error);
        });
    }
  }, [client, error, isInitialized]);
 
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
 
  return (
    <div className="p-4">
      <h1>Welcome to {appContext?.name || 'My Marketplace App'}</h1>
    </div>
  );
}



Step 6: Start Development


Run your app:
npm run dev

Then:
  1. Open your Sitecore Cloud Portal.
  2. Navigate to Marketplace.


    

  3. Find your registered app and open it in one of the configured extension points.
  4. Your app will now run inside Sitecore with secure communication.



Development Tips
  • Always test your app within Sitecore, not just on localhost.
  • Use the browser console in the Sitecore extension point for accurate logs.
  • Sitecore-specific functionality only works inside extension points.
Conclusion
The Sitecore XM Cloud Marketplace is a powerful way to extend the platform with custom 
applications tailored to your organization’s needs. By following the steps above, you can 
create, configure, and register your first app—from setting up a development environment to 
embedding it seamlessly in XM Cloud.
As the marketplace continues to evolve, it opens new opportunities for developers to innovate
and share apps across the Sitecore community. If you’re building for your team today, you’re
also preparing for tomorrow’s broader ecosystem.
References

Comments

Post a Comment

Popular posts from this blog

Setup New Project in Sitecore XMCloud – Part 1

Image
In my previous blog , I discussed about the XMCloud Introduction and features of XMCloud. In this blog I will show, how to create a new Project and environments in the Sitecore XM cloud. In the next blog, I will show how easily you can set up your local app development for XM Cloud and run the Sitecore XM Cloud project on your development machine. Prerequisites: • You must have one Organization account in Sitecore portal ( https://portal.sitecorecloud.io/ ) which has access to XMCloud.  And your account should be associated with that Organization account with admin access.  • Organization must have proper Sitecore licensing to run the XMCloud site in local docker environments. • Create your own Github account to link with XMCloud project. Steps to setup your project 1. Click on “Manage My projects” menu to open https://deploy.sitecorecloud.io/projects.io/projects site to Create a new project or manage existing one. 2. Then click on “Create New Project” button to cr...
Read more

Step by Step installation of Sitecore 10.3 on Azure PaaS

Image
  In this document we will learn how to setup Sitecore 10.3 XP on Azure PaaS. We shall briefly cover the step by step process and overview of Sitecore 10.3 XP setup. While doing the installation, I follow Deploying a new Sitecore environment to the Microsoft Azure App service . Thanks, Sitecore Team! Prerequisites: To setup Sitecore 10.3 on Azure PaaS, we shall need the following: Check PowerShellGet Module. If not found please install PowerShell Gallery Install the Azure Az PowerShell module. Download Sitecore Azure Toolkit 2.8.0 . This will provide a zip file that can be extracted and used for setup.  Deployment Topologies We will do the setup for Sitecore 10.3 XP. Sitecore XP product edition is the full Sitecore Experience Platform, which includes all Sitecore roles and services, including xConnect. This is a Sitecore Experience Platform configuration that runs: Three Sitecore roles: Content Delivery, Content Management, and Processing, as a single WebA...
Read more

Step by Step installation of Sitecore 10.3 on Docker

Image
  In this document, we will learn how to setup Sitecore 10.3 on docker desktop in Windows 11. We shall briefly cover the step-by-step process and overview of Sitecore 10.3 setup. While doing the installation in my windows, I followed Installation Guide for Developer Workstation with Containers . Thanks, Sitecore Team! Prerequisites - To setup Sitecore 10.3 on docker, we shall need the following - Docker Desktop Installed on Windows Desktop Docker Desktop support for windows containers 16 GB of RAM Approximately 50GB of free disk space for Sitecore container images. SSD storage is highly recommended. The default Sitecore container configuration uses specific ports. To avoid any conflicts, we should ensure the following ports are not being used by another process: 443, 8079, 8081, 8984, and 14330 To check the prerequisites for Sitecore 10.3 installation, please check the below link - Support Information - Sitecore compatibility table for Sitecore XP 9.0 and later Setup Files - Docker...
Read more